PC Direct 1995 May/PC Direct CD-ROM (May 1995).ISO/ipe/bri120e/disk1/bwusage.txt

Text File | 1994-07-31 | 142.5 KB | 3,806 lines

BWUSAGE.TXT Headings:

4.0 Software Distribution
    4.1 About BrightWorks' Software Distribution Capability
    4.2 Software Distribution Concepts
    4.3 BrightWorks' Software Distribution Modules
        4.3.1 BrightWorks Console/Administrative Program
        4.3.2 Update Program
    4.4 Distribution Configuration Options
        4.4.1 Running the Update Program
        4.4.2 Automating the Update Program
5.0 Filesets
    5.1 Introduction
        5.1.1 Fileset Features
        5.1.2 Access to Fileset Functions
        5.1.3 What's in this Chapter
    5.2 The Fileset Directory
        5.2.1 Defining a Fileset Directory
    5.3 Creating Filesets
    5.4 Managing Filesets
        5.4.1 Editing Filesets
        5.4.2 Renaming Filesets
        5.4.3 Copying Filesets
        5.4.4 Deleting Filesets
6.0 Scripts
    6.1 Introduction
        6.1.1 Script Features
        6.1.2 Access to Script Functions
        6.1.3 What's in this Chapter
    6.2 Creating Scripts
    6.3 Compiling Scripts
    6.4 Managing Scripts
        6.4.1 Editing Scripts
        6.4.2 Renaming Scripts
        6.4.3 Copying Scripts
        6.4.4 Deleting Scripts
        6.4.5 Incorporating BrightWorks Scripts
7.0 Software Distribution Script Language
    7.1 Introduction
        7.1.1 What's in this Chapter
    7.2 Notes on Syntax
    7.3 Script Functions
        7.3.1 Type of Functions
        7.3.2 User-defined Variables
    7.4 DOS Functions
    7.5 Easy System File Functions
    7.6 Windows System File Functions
    7.7 Miscellaneous Functions
    7.8 Rules and System Variables
        7.8.1 System Variables
        7.8.2 String Type Rules:
        7.8.3 Integer Type Rules:
    7.9 DOS Error Codes
8.0 Scopes
    8.1 Introduction
        8.1.1 Scope Features
        8.1.2 Access to Scope Functions
        8.1.3 What's in this Chapter
    8.2 Creating Scopes
    8.3 Scope Queries
        8.3.1 Creating a New Query
        8.3.2 Editing a Query
        8.3.3 Deleting a Query
        8.3.4 Applying a Query to the Scope
        8.3.5 Removing a Query from the Scope
        8.3.6 Creating a Complex Query
    8.4 Managing Scopes
        8.4.1 Renaming Scopes
        8.4.2 Copying Scopes
        8.4.3 Deleting Scopes
9.0 Packages
    9.1 Introduction
        9.1.1 Package Features
        9.1.2 Access to Package Functions
        9.1.3 What's in this Chapter
    9.2 Creating and Editing Packages
        9.2.1 Editing Packages
    9.3 Managing Packages
        9.3.1 Prioritizing Packages
        9.3.2 Renaming Packages
        9.3.3 Activating/Deactivating Packages
        9.3.4 Deleting Packages
    9.4 The Package Timer
10.0 Monitoring Software Distribution
    10.1 Introduction
        10.1.1 Access to the Software Distribution Log
        10.1.2 What's in this Chapter
    10.2 The Software Distribution Log
        10.2.1 Viewing Log History Details


4.0 Software Distribution

Welcome to BrightWorks' distribution features which enable software and
script distribution from a central location.


4.1 About BrightWorks' Software Distribution Capability

BrightWorks' software distribution capabilities provide a method for
distributing software packages and modifying workstation configuration
files from a central location.  The software distribution features
facilitate consistency among the workstations across your local area
network and improve the productivity of the LAN Administrator.

Distributing software and modifying workstation configuration files
from a central location on your network allows the LAN Administrator
to easily do the following:

o  update system executables and/or drivers (e.g., operating systems,
network drivers)

o  update system files (e.g., AUTOEXEC.BAT, CONFIG.SYS, WIN.INI, network
login script)

o  install and update software on user workstations across the local
area network

NOTE:  BrightWorks' Software Distribution capabilities can be used to
distribute software and/or scripts to any workstation in the BrightWorks
local site (i.e., the site which identifies the Fusion program
directory).  Sites are discussed in detail in section 13.2.1 entitled
"Maintaining LAN Sites."


4.2 Software Distribution Concepts

An understanding of the following concepts will help you in gaining full
advantage of BrightWorks' software distribution capabilities:

o  Fileset - A file that contains one or more compressed files.
Each compressed file may also indicate a target directory structure in
which the file should be decompressed.  For example, assume a fileset
named NEW_INI_FILES.  The fileset might consist of two files: WIN.INI
and SYSTEM.INI which have been defined to be decompressed into a
target directory named PUB\WIN.310.

o  Script - A sequence of one or more commands which define an operation
to be performed on a workstation receiving a distribution.  For example,
a script might include the commands to add a new group to the Windows
Program Manager, to copy file(s) from one location to another, or to
change parameters within certain files.

o  Scope - A group of one or more workstations that have been identified
to receive a distribution.  For example, to distribute a script to all
386 workstations, you must create a scope which includes the 386 workstations.

o  Package - The distributed object which contains scheduling information,
as well as a fileset and/or script and a scope.

The package being created is named "Updated INI Files," as indicated in
the dialog box title bar.  The package is scheduled to be distributed on
6/30/1994.  The package consists of the fileset named "NEW_INI_FILES,"
which will get distributed to all nodes included in the scope named
"LOCAL NODES."

The following key features help you distribute software across your LAN:

o  Creating filesets which include files to be installed on remote
workstations.

o  Creating scripts to be executed by remote workstations.

o  Defining scopes of workstations to receive distributed packages.

o  Creating and scheduling packages which consist of a scope and one
fileset and/or one script.

o  Monitoring package progress via the Software Distribution Log History
dialog box.


4.3 BrightWorks' Software Distribution Modules

The BrightWorks software distribution capabilities interact with two
major functional modules.  As an introduction to software and script
distribution, this section briefly describes the following modules:

o  BrightWorks console and administrative functions
o  Remote workstation update program (SDUPDATE.EXE)

NOTE:  BrightWorks' software distribution capabilities are provided with
the inventory capabilities discussed in Part Three of this manual.

4.3.1 BrightWorks Console/Administrative Program

BWORKS.EXE is the BrightWorks console and administrative program.  This
program provides access to all BrightWorks capabilities.  This main module
is a Windows-based program and is intended to be used by the LAN network
manager to perform all software distribution functions.

The software distribution functions available from the BrightWorks console
include:
o  Scope definition and management
o  Script creation and management
o  Package creation, scheduling and management
o  Pre-defined and custom distribution report generation

4.3.2 Update Program

The update program (SDUPDATE.EXE) must be executed from each remote
workstation to enable the workstations to receive the distributed
packages they have been sent.  Upon BrightWorks installation, the update
program is copied into the BWORKS program directory.

The update program is DOS-based and must be executed from the machine
which is to be updated.  To ensure that SDUPDATE.EXE is executed on a
regular basis, the command can be placed in the system login script.
Refer to the next section entitled "Distribution Configuration Options."

NOTE:  WSDUPD.EXE is the BrightWorks update program which handles the script
functions related to installing Windows software.  This program must not be
directly run by the user--it is automatically loaded when the ADDGROUP,
ADDITEM or SCHEDULEWIN Windows System File script functions are used.  Refer
to section 7.6 entitled "Windows System File Functions."


4.4 Distribution Configuration Options

The update program SDUPDATE.EXE must be run from each workstation in
order for it to receive the distributed packages it has been sent.
Upon BrightWorks installation, the update program is copied into the
BWORKS program directory.

The SDUPDATE program's syntax is as follows:

SDUPDATE [drive:[\path]]

in which drive and path are optional parameters.  The brackets are not typed.

Consider the following examples:

Example                 Result
SDUPDATE                SDUPDATE will look in the current directory.
SDUPDATE F:             SDUPDATE will look in the current directory
            on drive F:.
SDUPDATE F:\path        SDUPDATE will look in the directory F:\path.


NOTES: a - The Btrieve Record Manager must be loaded before running
SDUPDATE.EXE.  Refer to the section entitled "Consider Improving
BrightWorks' Database Performance" in Chapter 3 of the LAN Inventory manual
for a  discussion on the Btrieve options.
b - When running the Brequestor, BSPXCOM and BROUTER must also be loaded
on the file server.  For details on loading these programs, refer to
your Novell documentation.
c -  When running SDUPDATE.EXE in a DOS box, you must load another
session of BREQUEST by entering the following command:

     BREQUEST /D:17000 /L

After running SDUPDATE, end the additional session by issuing the
ENDBTRV command.

4.4.1 Running the Update Program

Use the following procedure to manually run the update program at a
workstation.

1.  At the workstation which is to receive the distributed package, load
    the Btrieve Record Manager.

    Either Btrieve or Brequest can be used.  Refer to section 12.6.3 entitled
    "Consider Improving BrightWorks' Database Performance" for a discussion
    on the Btrieve options.

2.  Make the BrightWorks directory your current directory.

    Use the DOS CD command to change into the BWORKS program directory,
    or map a physical drive to the BWORKS directory.

3.  Execute the SDUPDATE.EXE program.

    For example, enter the following at the DOS command line:

    SDUPDATE

    Upon executing SDUPDATE, several messages will display at the workstation.
    If the user has not been given the option to refuse the update or
    change the installation path, then the update program will continue
    automatically (e.g., the package's script or fileset will be installed
    at the workstation).

    a. If you are given the option of refusing the package, then the
    prompt displays.  To install the package at this time, type <Y>.
    To install the package another time (e.g., the next time the update
    program is run), type <N>.

    NOTE:  If the date or maximum number of times has expired and the
    package is configured to 'force upgrade,' then the package will be
    installed regardless of the user's response to this prompt.

    b. If you are given the option of overriding the installation path,
    then the prompt displays.  To override the default installation path,
    type <Y>.  To accept the default installation path, type <N>.  If
    you type <Y> to override the default installation path, you are
    prompted to specify a new installation path.  Type the new path and
    press the <ENTER> key.  The update program continues, and the package
    is installed.

4.4.2 Automating the Update Program

To ensure that SDUPDATE is executed on a regular basis, the command can
be placed in the system login script.

The following example illustrates SDUPDATE being executed from within
the system login script.  (Refer section 35.0 for instructions on
configuring the Btrieve NLM or VAP.)

....
MAP G:=SERVER/SYS:FUSION
DRIVE G:
#BREQUEST /D:17000
#SDUPDATE
#ENDBTRV
....

where G:=SERVER/SYS:FUSION is the drive ID and complete path where the
BrightWorks files and update program are stored.





5.0 Filesets

Chapter 4 provided an introduction to BrightWorks' software distribution
capability.  This chapter discusses the creation and management of
filesets--the set of files to be installed on a remote workstation.



5.1 Introduction

A fileset is a set of files, stored in compressed format, to be installed
on a remote workstation.  Distributing filesets from a central location
simplifies a System Administrator's job.  Instead of physically moving
from workstation to workstation to install or upgrade application files, the
Administrator only needs to centrally distribute one fileset consisting
of the application files.  Upon receipt at a remote workstation, the
fileset contents are decompressed and copied onto the workstation's
hard drive.

5.1.1 Fileset Features

In addition to containing a number of files to be distributed, filesets
can be defined to create a target directory structure.  For example, if
you create a fileset which includes all files for Windows 3.1, you must
also define the contents of the SYSTEM subdirectory.  BrightWorks
can do this for you automatically by including the full path name of
every file included in the fileset.

Filesets and scripts are a powerful combination.  Consider the following
examples:

o  Packaging the latest WIN.INI file with a script which determines
whether the existing WIN.INI file is outdated.  The script will also
copy the new WIN.INI if an old file is detected.

o  Packaging the Novell IPXODI files and sending them to the scope of
nodes using IPX.  After the fileset is decompressed in the target
directory, the script will update the AUTOEXEC.BAT file to reflect the
use of IPXODI.

Filesets can be stored, used and reused as a resource within BrightWorks.
An administrator can create a new fileset, as well as edit, copy, rename
and delete a fileset.  The steps for each procedure are provided in this
chapter.

5.1.2 Access to Fileset Functions

Most fileset functions are accessed by choosing the Filesets command
from the Tools menu.  The Filesets dialog box displays listing all
available filesets.

The process of defining a directory in which filesets are saved (the
"default fileset directory") is performed by choosing the Distribution
command from the Administration menu.  From the sub-menu that displays,
choose the Preferences command.

5.1.3 What's in this Chapter

The following chart describes the sections in this chapter:

SECTION                         DESCRIPTION
The Fileset Directory           Discusses the fileset directory,
                and describes the procedures for its
                definition.

Creating Filesets               Describes procedures for defining new
                filesets.

Managing Filesets               Describes procedures for editing, renaming,
                copying and deleting filesets.


5.2 The Fileset Directory

The fileset directory defines the path in which filesets are stored.
Upon saving a fileset, a copy of the files that are included in the
fileset are compressed.  They are stored in a file which is placed in the
fileset directory defined at the time the fileset is saved.  For example,
if your fileset directory is defined as F:\FUSION\FILESETS, then the
filesets that you create will be stored in the F:\FUSION\FILESETS directory.

5.2.1 Defining a Fileset Directory

Use the following procedure to define the directory in which filesets
should be stored.

1.  Choose the Distribution command from the Administration menu.  From
    the sub-menu that displays, choose the Preferences command.

    The Preferences dialog box displays.

2.  Choose the Browse button to define the pathname into which the
    compressed filesets are to be stored.

    The Path Browse dialog box displays enabling you to select from
    the lists of Drives and Directories.  Click on the Drives and
    Directories fields to select the desired pathname.

3.  When the pathname is selected, choose the OK button.

    The Path Browse dialog box closes, and the selected pathname displays
    in the Path to Filesets field of the Preferences dialog box.

4.  Choose the Save button to define the fileset directory.

    All saved filesets will be stored in the defined directory.

NOTE:  The fileset directory instructs the update program as to where
the filesets are located.  As a result, changing the fileset directory
after you have created filesets and included them in packages can
invalidate those packages.  If you change the default directory, you must
also copy all fileset files (*.SET) into the new fileset directory.
Be sure that each user has the same drive letter mapped to the same
server/volume specified in the Preferences dialog box.  Also, you cannot
store filesets on a non-network drive.


5.3 Creating Filesets

Use the following procedure to create a new fileset.

1.  Choose the Filesets command from the Tools menu.

    The Filesets dialog box displays listing the names of all defined
    filesets.

2.  Choose the New button.

    The New Fileset dialog box displays prompting you to enter a name
    for the new fileset.

3.  Enter the new fileset name, and choose the OK button.

    A fileset name can be up to 80 characters, and all typed characters
    are valid.

    Upon choosing the OK button, the Edit Fileset dialog box displays
    prompting you to define the contents of the new fileset.

    The fileset name being created or edited displays in the title bar of
    the Edit Fileset dialog box. The name of the fileset being created
    is "1994 Budget Files."

    For each file included in the fileset, the following information displays:
    File Name, Original Size, Compression Ratio, Date, Time, and Path.  The
    file list area is empty for new filesets.

    The Filename field in this dialog box displays the name of the file
    which will hold the compressed fileset. Upon saving the fileset, a
    compressed copy of all of the listed files will be stored in the file
    named "1994BUDG.SET."  This file is automatically created by BrightWorks
    when the fileset is created.  It is stored in the fileset directory
    which is currently defined.

4.  To add a file to the fileset, choose the Add button.

    The Add File dialog box displays.  This dialog box is a standard
    Windows dialog box used for opening, selecting and browsing files.

5.  Make selections from the Directories and Drives lists to find the file(s)
    to include in the fileset.

    For example, choose the Drives down arrow button, and click on Drive C:
    to display the directories on drive C.  From the list of directories
    which displays, click on one to display its file list.

6.  Select a file(s) from the File Name list.

    Multiple files can be selected using the Windows extended select
    procedures (i.e., hold down the <CTRL> or <SHIFT> key while selecting
    files).

7.  To include the selected file(s)' path in the Edit Fileset dialog box,
    enable the Include Path option.

    Placing a checkmark in this field causes the full pathnames of each
    selected file to be listed in the Edit Fileset dialog box.  (Step #9
    below provides the option to instruct the fileset to create the
    directory structure at the receiving workstation.)

8.  Choose the OK button.

    Upon choosing the OK button, the selected files are listed in the Edit
    Fileset dialog box.  Only the File Name and Path information display
    at this time.  The other fields are not available until the fileset is
    saved.

9.  Enable or disable the Create Directory Structure option.

    Enabling this option causes the full pathnames of each file listed in
    the Edit Fileset dialog box to be created at the receiving workstation.
    For example, assume that this option is enabled and a file is listed in
    the Edit Fileset dialog box as \USER\MARY\INVOICE.DOC.  In this
    case, the directories USER and MARY will be created at the receiving
    workstation if they do not already exist.

NOTE:  A fileset is always decompressed into the target directory that
is specified when creating a package.  In the above example, if the Create
Directory Structure option is checked and the fileset is included in a
package that has a default path of C:\SALES, then the INVOICE.DOC file
will be decompressed into C:\SALES\USER\MARY.

10. To save the fileset contents, choose the Save button.

    The changes made to a fileset are only committed to upon choosing the
    Save button.  The Updating Fileset dialog box displays while the
    fileset contents are being saved and compressed.  If you attempt to
    close the Edit Filesets dialog box without saving, you are prompted to
    save the fileset changes.

    The fileset is created and added to the Filesets dialog box.


5.4 Managing Filesets

This section describes the procedures for editing, renaming, copying and
deleting filesets.

5.4.1 Editing Filesets

Editing a fileset may become necessary in order to add or delete a
file according to a change in a fileset's intent.

NOTE:  It is recommended that you temporarily deactivate any packages
which use the fileset you intend to edit.

Use the following procedure to edit the contents of a fileset.  The
procedure assumes that you have already chosen the Filesets command from
the Tools menu to display the Filesets dialog box.

1.  Select the fileset from the list of Filesets, and choose the Edit button.

    A fileset can also be selected for editing by double clicking on the
    fileset name in the Filesets dialog box.  The Edit Fileset dialog box
    displays listing all files included in the fileset.

    For each file in the fileset, the following information displays:

    o  File Name - the name of the file
    o  Original Size - the file size before compression
    o  Compressed Size - the file size after compression
    o  Ratio - the compression ratio
    o  Date - the file's creation date
    o  Time - the file's creation time
    o  Path - the file's path which displays only if the Include Path
    option is checked in the Add File dialog box.

NOTE:  Some files may show a 0% compression ratio.  This occurs when the
file is already compressed or when the file is very small.

2.  To add a file to the fileset, choose the Add button.

    The Add File dialog box displays.  Refer to the section above entitled
    "Creating Filesets" for detailed procedures on using this dialog box.

3.  To delete a file from the fileset, highlight the file name and choose
    the Delete button.

    A prompt displays asking you to confirm the deletion.  Choose the Yes
    button to continue with the delete action.

    If deleted, the file name is removed from the Edit Filesets dialog box.

4.  To save the edited fileset contents, choose the Save button.

    The changes made to a fileset are only committed to upon choosing the
    Save button.  The Updating Fileset dialog box displays while the
    fileset contents are being saved and compressed.  If you attempt to
    close the Edit Filesets dialog box without saving, you are prompted to
    save the fileset changes.

5.4.2 Renaming Filesets

Changing the name of an existing fileset renames all instances of the
former fileset name.  For example, the new fileset name is reflected in
the Filesets dialog box as well as in any packages which include the fileset.

Use the following procedure to rename a fileset.  The procedure assumes
that you have already chosen the Filesets command from the Tools menu to
display the Filesets dialog box.

NOTES: a - A fileset can be renamed even if it is part of an actively
scheduled package.
b - The name of the .SET file which is maintaining the compressed fileset
and is stored in the fileset directory does not change.

1.  To rename a fileset, select the fileset name from the list of Filesets,
    and choose the Rename button.

    The Rename Fileset dialog box displays prompting you to enter a new
    fileset name.

2.  Enter the new fileset name, and choose the OK button.

    The new fileset name displays in the Filesets dialog box, and the
    old name is removed.  All attributes of the old fileset are preserved
    in the renamed fileset (i.e., the fileset contents do not change).

5.4.3 Copying Filesets

Use the following procedure to copy a fileset.  The procedure assumes that
you have already chosen the Filesets command from the Tools menu to display
the Filesets dialog box.

NOTE:  A fileset can be copied even if the original fileset is part of
an actively scheduled package.

1.  To copy a fileset, select the fileset name from the list of Filesets,
    and choose the Copy button.

    The Copy Fileset dialog box displays prompting you to enter a name
    for the new fileset.

2.  Enter the new fileset name, and choose the OK button.

    The new fileset name is added to the Filesets dialog box.  The new
    fileset contents are identical to the original fileset contents.

5.4.4 Deleting Filesets

Use the following procedure to delete a fileset.  The procedure assumes
that you have already chosen the Filesets command from the Distribution
menu to display the Filesets dialog box.

NOTE:  A fileset that is part of a scheduled package cannot be deleted.

1.  To delete a fileset, select the fileset from the list of Filesets,
    and choose the Delete button.

    A prompt displays asking you to confirm the deletion.

2.  Choose the Yes button to delete the fileset.

    The fileset name is removed from the Filesets dialog box.



6.0 Scripts

Chapter 5 discussed the creation and management of filesets.  This
chapter discusses the creation and management of scripts--a series
of commands to be executed on a remote workstation.



6.1 Introduction

A script is a series of commands to be executed on a remote workstation.
Scripts must be written according to a defined syntax, and they must be
compiled successfully to be included in a package.

NOTES: a - The commands and instructions for using BrightWorks' software
distribution scripting language are documented in Chapter 7 of this
manual.
b - BrightWorks is shipped with several script files that can be
customized for your own use. Refer to section 6.4.5 entitled "Incorporating
BrightWorks Scripts."

6.1.1 Script Features

The ability to send scripts from a central location can be used to
contribute to the consistency and standardization of LAN workstations.
Scripts enable the LAN administrator to easily do the following:

o  update system executables and/or drivers (e.g., operating systems,
network drivers)

o  update system files (e.g., AUTOEXEC.BAT, CONFIG.SYS, WIN.INI,
network login script)

o  install software on a user's workstation

A user can create a new script, as well as edit, compile, copy, rename
and delete a script.  The steps for each procedure are discussed in this
chapter.

6.1.2 Access to Script Functions

Script functions are accessed by choosing the Scripts command from the
Tools menu.  The Scripts window displays listing all available scripts.

Script management is performed by either choosing the buttons in the
Scripts window or by choosing the corresponding commands from the File menu.
For example, when the Scripts window is active, a new script can be
created either by choosing the New button in the Scripts window or by
choosing the New Script command from the File menu.

The Edit menu commands provide the standard Cut, Copy and Paste functionality
for use during script editing.

6.1.3 What's in this Chapter

The following chart describes the sections in this chapter:

SECTION                 DESCRIPTION
Creating Scripts        Describes procedures for defining new scripts.

Compiling Scripts       Describes the procedures for compiling scripts.

Managing Scripts        Describes procedures for editing, renaming,
            copying and deleting scripts.


6.2 Creating Scripts

A script is created by assigning both a script name and a file name to
the new script.  The script name is used for identification purposes
within BrightWorks.  For example, it is immediately obvious that the
script named "Upgrade to Win 3.1" is responsible for upgrading the
Windows software to version 3.1.  The script file name identifies the
ASCII text file containing the script commands.  The script file name
must be a valid DOS file name (e.g., 8 characters plus the 3 character
extension).

After assigning the script name and file name, an "empty" script is created.
The empty script must be edited in order to add commands.

Use the following procedure to create a new script.

1.  Choose the Scripts command from the Tools menu.

    The Scripts window displays listing the names of all defined scripts.
    For each script, the last compilation date, the status and the file name
    also displays.

2.  Choose the New button.

    The Open New Script dialog box displays prompting you to enter the
    name, file name and destination directory for the new script.

3.  Enter the new script information, and choose the OK button.

    The script name can be up to 80 characters, and all typed characters
    are valid.  The script file name must follow the standard DOS conventions.

NOTES: a - It is recommended that .SCR be assigned as the extension for
all script file names.  A script file is a text file and can be edited
with an external editor.
b - The scripts must reside on a network drive to which all users who will
receive the script have access

Upon choosing OK, the message "This file does not exist.  Create the file?"
displays.  Choose the Yes button to create the script file and display the
Script Editor window.

The script name being edited displays in the title bar of the Script Editor
window.  All commands that are included in this script are listed.  (The
list is empty for new scripts.)

4.  Type the script commands.

    Script commands can be directly typed into the Script Editor window.
    Commands can also be selected from a list of commands by choosing the
    Functions button in the Script Editor window or the Paste Script
    Function command from the BrightWorks Edit menu (refer to the
    explanation below).

    The script compiler requires one command per line.  No error checking
    is performed until the script is compiled.

    Optional comments can be placed in the script preceded by a semi-colon.
    These comments are ignored at compile time.  For example:

    ;This is a comment.

NOTE:  The commands and rules for using the scripting language are
documented in Chapter 7 of this manual, "Software Distribution Script
Language."

Standard editing functions are available from the Edit menu on the
BrightWorks menu bar.  The commands that are available from the Edit menu
are as follows:

o  Undo - removes the last change made to the script.

o  Cut - copies a block of selected text to the clipboard and removes the
text from the Script Editor window.

o  Copy - copies a block of selected text to the clipboard.

o  Paste - places the block of text from the clipboard into the Script
Editor window at the current cursor location.

o  Paste Script Function - displays the Choose Script Function dialog box.
This dialog box allows you to select a function (from a list of all script
functions) to be placed in the script at the current cursor location.  A
function can be selected by either double clicking on the function name,
or highlighting the name and choosing the OK button.  Choosing the Help
button displays help text for the highlighted function.

o  Find - searches the script for a user-specified text string.

o  Next - searches the script for the next occurrence of the user-specified
text string.

o  Replace -  searches the script for a user-specified text string and
replaces the found text with another user-specified text string.

o  Fonts - enables you to select the font, style and size of the script type.

NOTE:  During script editing, the status bar in the BrightWorks application
window indicates the current line and column position of the typing cursor.

5.  To compile the script, choose the Compile button in the Script Editor
    window.

    Refer to the next section for details on compiling scripts.

6.  To save the script contents, choose the Save button in the Script
    Editor window.

    The saved script contents are stored in ASCII text format.  The script
    must be compiled to be used in a package.  To compile the script, follow
    the procedure below entitled "Compiling Scripts."

7.  Choose the Close button to close the Script Editor window.

    If you did not save the script changes as in Step #6 above, you are
    prompted to do so now.  Choose the Yes button to save the script changes,
    or choose No to close the Script Editor without saving any changes.

    The new script is added to the Scripts window.  The status of all
    uncompiled scripts is 'ASCII.'   A script must be compiled to be used
    in a package.


6.3 Compiling Scripts

The Status field in the Scripts window indicates the status of each script.
Script status can be either ASCII or COMPILED.  A script's status must be
COMPILED to be used in a package for distribution.

The commands and instructions for using the scripting language are documented
in Chapter 7 of this manual, "Software Distribution Script Language."
The compilation process checks the syntax and validity of the script's
commands.

Use the following procedure to compile a script.  The procedure assumes
that you have already chosen the Scripts command from the Tools menu to
display the Scripts window.

1.  To compile a script, select the script in the Scripts window and
    choose the Compile button.

    While a compile is in progress, the Compile Status dialog box displays.

    When the compile is complete, the Status field in the Compile Status
    dialog box indicates success or failure.  If the compile fails, the
    Function field indicates the first function found which has invalid
    parameters.  The Statistics area indicates the total number of lines in
    the script (Lines field) and the number of errors found (Errors field).

2.  Choose the OK button to continue.

    If the script compile is successful, then choose the Close button in
    the Script Editor window to return to the Scripts window which shows
    the script's status as COMPILED.

    If the script compile fails, then the Compiler Messages dialog box
    displays listing the first script line which contains errors.

3.  To correct a compiler error condition, double click on an error line
    in the Compiler Messages dialog box.

    The Script Editor window displays with the script that you are
    attempting to compile.  The selected error line is automatically
    highlighted.

4.  Correct all error conditions, and attempt to re-compile the script.

    Refer to Chapter 7 of this manual for details on the scripting rules
    and commands.

    After successful compilation of the script, the script can be used
    in a package.

NOTE:  If you edit a script that has already been compiled, the script
must be successfully re-compiled in order to be used in a package.
Refer to the "Last Comp" field in the Scripts window to discover the date
on which the file was last compiled.


6.4 Managing Scripts

6.4.1 Editing Scripts

Editing a script may be necessary under two circumstances:

o  Existing scripts might need to be edited in order to add or delete
commands according to a change in a script's intent.

o  When a script compilation fails, the script must be edited to resolve
the error(s).

NOTE:  It is recommended that you temporarily deactivate any packages
which use the script you intend to edit.

Use the following procedure to edit the contents of a script.  The
procedure assumes that you have already chosen the Scripts command from
the Tools menu to display the Scripts window.

1.  Select the script from the Scripts window, and choose the Edit button.

    A script can also be selected for edit by double clicking on the script
    name in the Scripts window.  The Script Editor window displays.

    The script name being edited displays in the title bar of the Script
    Editor window.  All commands that are included in this script are listed.

2.  Edit the script commands.

    Script commands can be directly typed into the Script Editor window.
    Commands can also be selected from a list of commands by choosing the
    Functions button in the Script Editor window or the Paste Script Function
    command from the BrightWorks Edit menu.

    The script compiler requires one command per line.  No error checking is
    performed until the script is compiled.

NOTES: a - The commands and rules for using the scripting language are
documented in Chapter 7 of this manual, "Software Distribution Script
Language."
b - During script editing, the status bar in the BrightWorks application
window indicates the current line and column position of the typing cursor.

3.  To compile the script, choose the Compile button in the Script Editor
    window.

    Refer to section 6.3 entitled "Compiling Scripts" for details on
    compiling scripts.

4.  To save the edited script contents, choose the Save button in the
    Script Editor window.

5.  Choose the Close button to close the Script Editor window.

NOTE:  If you edit a script that has already been compiled, the script
must be successfully re-compiled in order to be used in a package.

6.4.2 Renaming Scripts

Changing the name of an existing script renames all instances of the
former script name.  For example, the new script name will be reflected
in the Scripts window as well as in any packages which include the script.

Use the following procedure to rename a script.  The procedure assumes
that you have already chosen the Scripts command from the Tools menu to
display the Scripts window.

NOTE:  A script can be renamed even if it is part of an actively scheduled
package.

1.  To rename a script, select the script name from the Scripts, and choose
    the Rename button.

    The Rename Script dialog box displays prompting you to enter a new
    script name.

2.  Enter the new script name, and choose the OK button.

    The new script name displays in the Scripts window, and the old name
    is removed.  All attributes of the old script are preserved in the
    renamed script (i.e., the script contents do not change).

NOTE:  The script rename procedure only changes the script name--the script
file name does not change.

6.4.3 Copying Scripts

Use the following procedure to copy a script.  The procedure assumes that
you have already chosen the Scripts command from the Tools menu to display
the Scripts window.

NOTE:  A script can be copied even if the original script is part of an
actively scheduled package.

1.  To copy a script, select the script from the Scripts, and choose the
    Copy button.

    The Copy Script dialog box displays prompting you to specify a name,
    file name and destination directory for the new script.  The script
    name can be up to 80 characters, and all typed characters are valid.
    The script file name must follow the standard DOS conventions and can
    reside in any directory.

NOTE:  It is recommended that .SCR be assigned as the extension for all
script file names.

2.  Enter the new script information, and choose the OK button.

    The new script name is added to the Scripts window.  The new script is
    populated with the same commands as the original script.

6.4.4 Deleting Scripts

Use the following procedure to delete a script.  The procedure assumes that
you have already chosen the Scripts command from the Tools menu to display
the Scripts window.

NOTE:  A script that is part of a scheduled package cannot be deleted.

1.  To delete a script, select the script from the Scripts, and choose the
    Delete button.

    A prompt displays asking you to confirm the deletion.

2.  Choose the Yes button to delete the script.

    If deleted, the script name is removed from the Scripts window.

NOTE:  The delete action only deletes the script name from the Scripts
window.  The corresponding .SCR file is not deleted.  Therefore, if a script
name is inadvertently deleted, you can create a new script and assign the
same script file name to retrieve the deleted script contents.

6.4.5 Incorporating BrightWorks Scripts

BrightWorks is shipped with several pre-defined scripts that can be
customized for use in your environment.  Upon BrightWorks installation, the
script files are copied into the BWORKS program directory.

The table below lists the purpose of each script and indicates the script
file name:

PURPOSE                                 FILE NAME
Word for Windows Local Installation     LOCAL.SCR
Find and Delete a Program File          FINDDEL.SCR
AUTOEXEC.BAT Replacement                AUTORLP.SCR
AUTOEXEC.BAT Append                     AUTOAPP.SCR
AUTOEXEC.BAT Modification               AUTOMOD.SCR
CONFIG.SYS Replacement                  CFGRPLMT.SCR
CONFIG.SYS Append                       CFGAPP.SCR
CONFIG.SYS Modification                 CFGMOD.SCR
DOS Upgrade 3.X to 6.X                  DOS3TO6.SCR
DOS Upgrade 4.X to 5.X                  DOS4TO5.SCR
DOS Upgrade 5.X to 6.X                  DOS5TO6.SCR
Novell NETX Update                      NETXUP.SCR
Novell Wkst ODI/VLM/IPX Driver          NETBAT.SCR
Startup Batch File Update
VLM Upgrade                             VLMUPGRD.SCR
Send Text Message to Network Users      TYPE.SCR
Copy Files to Server                    CPFS.SCR
Windows Network Installation            WININST.SCR
Windows Add Program Group               ADDGROUP.SCR
Windows Add Program Item                ADDITEM.SCR
Windows INI Replacement                 INIRPL.SCR
Windows INI Append                      WINIAPPD.SCR
Windows INI Modification                WININIMD.SCR
Windows Spooler Setting in INI          WINSPOOL.SCR
Install SMRAGENT.EXE                    AGENT.SCR
Windows Wallpaper Update                WALLPAPR.SCR
CC:MAIL for Windows installation        NETINS.SCR

Use the following procedure to incorporate a pre-defined script into
BrightWorks.

1.  Choose the Scripts command from the Tools menu.

    The Scripts window displays.

2.  Choose the New button.

    The Open New Script dialog box displays.

3.  Enter a name for the script in the Script Name field.

    The script name can be up to 80 characters, and all typed characters
    are valid.  The script name is used within BrightWorks to identify the
    script.  For example, if you are incorporating the script which adds a
    group to the Program Manager desktop, then you might want to define
    the script name as ADD PROGRAM GROUP.

4.  Select the script to be incorporated into BrightWorks.

    Select a script from the list of script file names.  For example, if
    you want to incorporate and edit the script which adds a group to the
    Program Manager desktop, then you would select the ADDGROUP.SCR file.

5.  Choose the OK button.

    The Script Editor window displays listing the commands for the chosen
    script.

6.  Edit the script commands.

    The commands and rules for using the scripting language are documented
    in Chapter 7 of this manual, "Software Distribution Script Language."

7.  Choose the Compile button in the Script Editor window to compile the
    script.

    Refer to section 6.3 entitled "Compiling Scripts" for details on
    compiling scripts.

8.  Choose the Save button in the Script Editor window.

    The script contents are saved.

9.  Choose the Close button to close the Script Editor window.

    The new script is added to the Scripts window.  Note that a script
    must be compiled to be used in a package.



7.0 Software Distribution Script Language

Chapter 6 discussed creating and managing scripts. This chapter lists the
variables and rules for each function in the BrightWorks scripting language.



7.1 Introduction

A script is a series of commands to be executed on a remote workstation.
Scripts must be written according to a defined syntax, and they must be
compiled successfully to be included in a package.

The commands and instructions for using the BrightWorks software distribution
scripting language are discussed in this chapter.  The procedures for
creating, compiling and managing scripts are discussed in the Chapter 6
entitled "Scripts."

7.1.1 What's in this Chapter

The following chart describes the sections in this chapter:

SECTION                         DESCRIPTION
Notes on Syntax                 Discusses several items to note regarding
                the general format of the script language
                functions.

Script Functions                Discusses the type of functions available,
                and summarizes their parameters and purpose.

DOS Functions                   Lists each DOS function, providing the
                following: the function parameters, a
                description, tips for using the function,
                its return values and an example for using
                the function in a script.

Easy System File Functions      Lists each Easy System File function,
                providing the same information as above.

Windows System File Functions   Lists each Windows System File function,
                providing the same information as above.

Miscellaneous Functions         Lists each Miscellaneous function, providing
                the same information as above.

Rules and System Variables      Lists the allowable values for each
                parameter, and defines the variable rules.

DOS Error Codes                 Lists the DOS error codes that can be
                returned from the script functions.



7.2 Notes on Syntax

The following items must be noted when writing scripts:

o  Only one command can be placed on a line.

o  The syntax for each command/function is as follows:

    FUNC_NAME [parameter1], [parameter2], ...[parameterN]

o  Unless otherwise noted, each function returns a 0 if it is successful
(i.e., the system variable [retval] is set to 0).  The action to be taken
as a result of a script's return code is defined when the script is
included in a package.  These "Advanced Package Options" are discussed in
Chapter 9.

o  Some functions take "optional" parameters.  The administrator should
decide whether or not to specify these parameters. If they
are not specified, an empty or NULL value must be passed to the compiler to
act as a placeholder.

For example, the COPY function has the following parameters:

    COPY [path] [filewild] [path] {filewild}

where the last parameter, {filewild}, is optional.  The COPY command below
provides an example for copying all .BAT files from the C: drive to the B:
drive, using a placeholder to stand for the last {filewild} parameter:

    COPY "C:\" "*.BAT" "B:\" ""

In this example, the files are not renamed and retain their original .BAT
extensions.


7.3 Script Functions

Each script "command" is treated as a "function" (e.g., a C function) that
has two basic properties:

o  each command has 0 to 4 parameters that it will be passed
o  most commands have a return code

As such, the script language supports user defined variables (of integer
and string type), as well as "system" variables.  When necessary, the
functions also implement return values from the parameters that are passed.

Each function has one or more parameters that can be passed.  In the
following discussions, the required parameters are surrounded by [ ], and
the optional parameters are surrounded by {  }.  Each parameter is the
name of a rule, whose allowable values are listed later in this chapter.

7.3.1 Type of Functions

The script functions are divided into the four major categories summarized
below:

DOS Functions (section 7.4):
FUNCTION        REQUIRED PARAMETERS             DESCRIPTION
ATTRIB          [path] [filewild] [attribute]   Changes the attributes of a
                        file or multiple files.

COPY            [path] [filewild] [path]        Copies a file or files to
        {filewild}                      another directory and file
                        name(s).

DELETEDIR       [path] [filename] {deleteopt}   Deletes a directory.

DELETEFILE      [path] [filewild]               Deletes a file or multiple
                        files.
FINDFILE        [path] [filewild] [strvar]      Finds a file.

MDIR            [path] [filename]               Creates a directory.

RENAME          [path] [filewild] [path]        Renames a source file(s).
        [filewild]

UPGRADEOS       [upgopt]                        Upgrades DOS version from
                        3.x-5.x to either 5.00
                        or 6.00.


Easy System File Functions (section 7.5):

FUNCTION        REQUIRED PARAMETERS             DESCRIPTION
ADDDEVICE       [strvalue1] [strvalue2]         Adds a new DEVICE= line to a
        [addopt]                        system file.

ADDLINE         [strvalue1] [strvalue2]         Adds a line of text to a
        [addopt]                        system file.

ADDPATH         [strvalue1] [strvalue2]         Adds a sub-directory to a
        [strvalue3] [addopt]            path environment variable.

CFGGETVALUE     [strvalue] [intvar]             Gets a numeric variable from
                        a system file.

CFGSETVALUE     [strvalue] [intvalue]           Sets a numeric variable in a
                        system file.

CFGGETSTRING    [strvalue] [strvar]             Gets a string variable from
                        a system file.

CFGSETSTRING    [strvalue1] [strvalue2]         Sets a string variable in a
                        system file.

REPLACEKEY      [strvalue1] [strvalue2]         Replaces a key value in a
        [strvalue3]                     system file.

REPLACELINE     [strvalue1] [strvalue2]         Replaces an existing line in
                        a system file with a new line.

REPLACELINE-ADD [strvalue1] [strvalue2]         Replaces or adds an existing
        [addopt]                        line in a system file.

SETSYSFILE      [path] [filename]               Sets a system file to be
                        manipulated.


Windows System File Functions (section 7.6):

FUNCTION        REQUIRED PARAMETERS             DESCRIPTION
ADDGROUP        [strvalue]                      Creates a new Program Manager
                        group.

ADDITEM         [strvalue1] [strvalue2]         Adds a new item to a Program
        [pathfile]                      Manager group.

GETINIINT       [pathfile] [strvalue1]          Gets a key value (integer)
        [strvalue2] [intvar]            from an INI file, and places
                        the result in a variable.

GETINISTR       [pathfile] [strvalue1]          Gets a key value (string)
        [strvalue2] [strvar]            from an INI file, and places
                        the result in a variable.

SCHEDULEWIN     [path] [filename] [text]        Schedules a file to be run
                        the next time the user runs
                        Windows.

WRITEINIINT     [pathfile] [strvalue1]          Writes a key value (integer)
        [strvalue2] [intvalue]          to an INI file

WRITEINISTR     [pathfile] [strvalue1]          Writes a key value (string)
        [strvalue2] [strvalue3]         to an INI file.


Miscellaneous Functions (section 7.7):

FUNCTION        REQUIRED PARAMETERS             DESCRIPTION
APPENDPATH      [strvar] [strvalue]             Appends the contents of a
                        string value to the end of a
                        string variable; however, it
                        first checks if the last
                        character of a string
                        variable is a "\".  If it
                        is not, APPENDPATH will
                        append a "\" and a value to
                        the variable.

ASSIGN          [intvar] [intvalue]             Performs a basic integer
                        assignment operation.

DEFINE          [text] [defineopt]              Used to create user defined
                        variables of a string or
                        integer type.

EXIT            [intvalue]                      Ends the script.

IF..THEN..ELSE  [intvalue1] [condoper]          Allows conditional processing
        [intvalue2]                     of functions.

NUMTOSTR        [strvar] [intvalue]             Converts a numeric value to
                        a string variable.

PAUSE           [text]                          Pauses execution of the
                        script until the user presses
                        a key.

REBOOT                                          Immediately reboots the
                        user's PC.

SHELL           [pathfile] {text}{shellopt}     Allows a user to execute an
                        external DOS batch file or
                        executable program.

STRCAT          [strvar] [strvalue]             Appends the contents of a
                        string value to the end of a
                        string variable.

STRCOMPARE      [strvar] [strvalue]             Does a byte for byte
                        comparison of two strings.

STRCOPY         [strvar] [strvalue]             Copies a value into a string,
                        overwriting the previous
                        contents of the string.

WRITELN         [strvalue]                      Writes a string value
                        (e.g., write to screen).


NOTE:  In the actual script, parameters are separated by a space; do not
type the brackets.

7.3.2 User-defined Variables

User-defined variables are defined by using the DEFINE command (see
Miscellaneous Functions) to create a string or integer user-defined
variable name.

User-defined variables must be defined before listing any script functions.
Also, the appropriate type must be used when calling a function that allows
user-defined variable names.  The functions that allow user-defined
variables, system variables and literal text use the phrases [strvar]
or [intvar] in their parameter listings.  Check the Rules discussion in
section 7.7 entitled "Rules and System Variables" for further details.


7.4 DOS Functions

The DOS function set is used for managing a machine's files and directories.
For example, files can be searched for, copied, deleted, renamed and
tagged with a specified attribute; directories can be created and deleted.

Return values are generated when appropriate (unless otherwise noted, the
functions return 0 if successful).  Any applicable system variables are
also noted.

Most DOS functions return a DOS error code if unsuccessful.  Refer to the
table in section 7.8 entitled "DOS Error Codes" for a list of the DOS error
codes that may be returned.

NOTES: a - When an "explicit <path>" is mentioned, it can take the form
of D:\PATH  (SERVER/VOLUME:\PATH is not currently supported).
b -  Some functions take optional "options."  The administrator should
decide whether or not to specify these options.
c - In the following function specifications, parameters in quotes
represent literal parameters; all other parameters represent rules.
The rules are listed in section 7.7 entitled "Rules and System Variables."

ATTRIB [path] [filewild] [attribute]

Parameter       Description and Notes
[path]          Source path to files. This path must exist.

[filewild]      The file name whose attributes are to be changed. May
        contain wildcards (? and *).

[attribute]     RO -  Read only
        RW - Read/Write
        A -    Set Archive bit
        SY -   System file
        H -    Hidden file
        SH -  Shareable (network <path> only)
        -A -   Turn off archive attribute
        -SY - Turn off system attribute
        -H -   Turn off hidden attribute
        -SH - Turn off shareable attribute (network <path> only)


Description - Changes the attributes of a file or multiple files.

Tip - To remove the Read Only attribute, use the RW attribute.
(There is no -RO attribute.)

Return Values:

[RETVAL] = 0 if successful

[RETVAL] = -1 if the SH or -SH attributes are used and the drive letter
specified in [PATH] is not a network drive

[RETVAL] = -2 if the SH or -SH attributes are used and no drive letter is
specified in [PATH]

[RETVAL] = DOS error code in all other cases

Example -  Set the AUTOEXEC.BAT file on a user's boot drive to Read Only:

    ATTRIB [BOOT_ROOT] "AUTOEXEC.BAT" RO


COPY [path] [filewild] [path] {filewild}

Parameter       Description and Notes
[path]          Source path of file to be copied.

[filewild]      Source file name to be copied.
        May contain standard DOS wild cards (? and *).

[path]          Destination path.

{filewild}      Optional destination file name.  (If not specified, *.*
        is assumed.)
        May contain standard DOS wild cards (? and *). May be used
        to rename file(s) during file copy.  If not used,
        the placeholder "" or NULL must be specified.


Description - Copies a file or files to another directory and file name(s).

Return Values:

[RETVAL] = 0 if file(s) are copied correctly
[RETVAL] = DOS error code if the function is unsuccessful

Example - Copy the WIN.INI file from the Windows directory found at login
to the local Windows directory.  Two examples of this are:

COPY [WINDIR] "WIN.INI" "C:\WINDOWS" ""

                 or

COPY [WINDIR] "WIN.INI" "C:\WINDOWS" NULL


DELETEDIR [path] [filename] {deleteopt}

Parameter       Description and Notes
[path]          Source path to the directory to be deleted. This path
        must exist.

[filename]      Directory name to be deleted.

{deleteopt}     Optional delete option: ALL - causes DELETEDIR to delete
        the specified directory and everything under it, including
        any subdirectories, hidden, system and read only files. If
        not used, NULL must be specified.


Description - Deletes a directory.

Tip - Use the ALL delete option with caution since it can delete entire
directory trees.

Return Values:

[RETVAL] = 0 if the directory is successfully deleted
[RETVAL] = DOS error code if the function is unsuccessful

Example - Delete the Windows directory found at login and all of its files
and sub-directories:

    DELETEDIR [WINDIR] ALL



DELETEFILE [path] [filewild]

Parameter       Description and Notes
[path]          Source path to the file(s) to be deleted. This path
        must exist.

[filewild]      File name(s) to be deleted.  Wild cards may be
        specified (? and *) to delete multiple files.


Description - Deletes a file or multiple files.

Return Values:

[RETVAL] = 0 if the file(s) are deleted
[RETVAL] = DOS error code if the function is unsuccessful

Example - Delete all .DOC files from the F:\UZR\JOHN sub-directory:

    DELETEFILE "F:\UZR\JOHN" "*.DOC"



FINDFILE [path] [filewild] [strvar]

Parameter       Description and Notes
[path]          Source path in which to search for files.  This path
        must exist.

[filewild]      The search criteria. May contain wildcards (? and *).

[strvar]        A string variable which contains the file name of the
        first file found.  (Before being used as a parameter,
        this variable must be defined using the DEFINE function.)


Description - Finds a file.

Return Values:

[RETVAL] = 0 and copies the name of the first file found into [STRVAL]
if successful
[RETVAL] = -1 and sets [STRVAL] to NULL if no files are found

Example -  Test for the presence of the NET.CFG file in the [NET.CFG]
directory:

    DEFINE "Result" STRING
    FINDFILE [NETCFG] "NET.CFG" RESULT


MDIR [path] [filename]

Parameter       Description and Notes
[path]          Path in which to create the new directory. This path
        must exist.

[filename]      Sub-directory to create. Wild cards may not be specified.


Description - Creates a directory.

Return Values:

[RETVAL] = 0 if the directory is successfully created
[RETVAL] = DOS error code if the function is unsuccessful

Example - Create the JOHN sub-directory in the UZR directory:

    MDIR "F:\UZR" "JOHN"



RENAME [path] [filewild] [path] [filewild]

Parameter       Description and Notes
[path]          Source path to files to be renamed. This path must exist.

[filewild]      Source file name to be renamed. May contain wildcards
        (? and *).

[path]          Destination path (can be different than [path] to enable
        moving files, but the drives must be the same).

[filewild]      New file name.  May contain wildcards (? and *).
        If so, the standards used by the DOS REN command are followed.


Description - Renames a source file(s).

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example -  Rename all .BAT files in the C:\ drive to .BAK:

    RENAME "C:\" "*.BAT" "C:\" "*.BAK"



UPGRADEOS [upgopt]

Parameter       Description and Notes
[upgopt]        5.00 - upgrade DOS version to 5.00
        6.00 - upgrade DOS version to 6.00


Description - Upgrades DOS version from 3.x-5x to either 5.00 or 6.00.

Tips:
1) In order for BrightWorks to have access to the upgraded DOS files,
EQUIP must first be run on a machine that has the desired DOS files.
For example, to upgrade a machine's DOS version to 6.00, EQUIP first must
be executed on a machine that has DOS 6.00.  By executing EQUIP from the
same directory in which the BrightWorks software distribution update
program (SDUPDATE.EXE) file is located, the DOS files become accessible
by BrightWorks.  Note also that the machine on which EQUIP is run must
not contain any system that modifies the machine's boot record
(e.g., OS/2, Windows NT).

NOTE:  Do not use this function on a workstation that has Windows NT
installed in a dual boot configuration.  It will cause the boot menu to be
lost.  The PC will boot DOS only.

2) The machine must be rebooted after the script is executed.  Use the
REBOOT function as the last script function.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example -  Upgrade a user's DOS version to 5.00:

    UPGRADEOS 5.00
    IF [RETVAL]=0
        ...
        ; copy DOS files, edit CONFIG.SYS, etc.
        REBOOT
    ENDIF



7.5 Easy System File Functions

The Easy System File functions allow for easy manipulation of basic
system files, such as CONFIG.SYS, AUTOEXEC.BAT, NET.CFG, or a login script.
(Use the Windows System File functions to edit .INI files.)

Most Easy System File functions return a DOS error code if unsuccessful.
Refer to the table in section 7.8 entitled "DOS Error Codes" for a list of
the DOS error codes that may be returned.

NOTE:  Prior to using any of the functions in this category, you must call
SETSYSFILE.  Also, none of the functions will create a backup of the file
that they are modifying; however, a file will not be modified if a function
fails.  It is your responsibility to backup any file as necessary.

All of the Easy System File functions make use of a "key" value.  This
value is used to search the file to aid in determining where to make a
modification.  All key searches are case insensitive.  If a key is found,
its corresponding value is defined as the first non- whitespace (e.g. tab,
cr/lf, =, etc.) group of characters after the found key value.
For example, consider the following line:

    PATH=C:\DOS;C:\WINDOWS

If "PATH" is specified as the key, then the corresponding value is
"C:\DOS;C:\WINDOWS."  However, consider the following line:

    STACKS 9,256

If "STACKS" is specified as the key, then the corresponding value is "9,256."
As a result, an equal sign is not necessary to identify a value that
you might want to edit.

NOTE:  In the following function specifications, parameters in quotes
represent literal parameters; all other parameters represent rules.  The
rules are listed later in this chapter.


ADDDEVICE [strvalue1] [strvalue2] [addopt]

Parameter       Description and Notes
[strvalue1]     The path and driver name (e.g. C:\WINDOWS\EMM386.EXE).

[strvalue2]     The key value to search for (e.g. HIMEM.SYS).

[addopt]        Where [strvalue1] is to be placed: either BEFORE or AFTER
        [strvalue2].


Description - Adds a new DEVICE= line to a system file (typically the
DOS CONFIG.SYS).

Tip - If [strvalue2] is a null string or the key is not found, ADDDEVICE
will add [strvalue1] in the position of the file indicated by [addopt].

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example - Place "DEVICE=C:\WINDOWS\EMM386.EXE" after the "DEVICE=HIMEM.SYS"
line in the CONFIG.SYS file:

    SETSYSFILE "C:\" "CONFIG.SYS"
    ADDDEVICE "C:\WINDOWS\EMM386.EXE" "HIMEM.SYS" AFTER


ADDLINE [strvalue1] [strvalue2] [addopt]

Parameter       Description and Notes
[strvalue1]     The entire line of text you wish to add.

[strvalue2]     A reference key value to be positioned relative to
        [strvalue1].  This is a "keyword" that will be searched
        for in the file.  Specify as much or as little as you like.
        When the first occurrence of the keyword in a line is found,
        that line is used as the reference.

[addopt]        Specify where [strvalue1] is to be placed: either BEFORE or
        AFTER [strvalue2].


Description - Adds a line of text to a system file.

Tip - If [strvalue2] is a null string, ADDLINE will place [strvalue1] in
the position of the file indicated by [addopt].

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example -  Add a new line to the end of a user's CONFIG.SYS file:

    SETSYSFILE "C:\" "CONFIG.SYS"
    ADDLINE "THIS IS NEW.." "" AFTER

NOTE:  As in the example above, non-specified parameters
(e.g., [strvalue2]) can be indicated by empty quotes.  Entering NULL
with no quotes is also acceptable.



ADDPATH [strvalue1] [strvalue2] [strvalue3] [addopt]

Parameter       Description and Notes
[strvalue1]     The name of the path environment variable to edit (PATH for
        DOS, or DPATH for OS/2, or TEMP, etc).

[strvalue2]     The sub-directory to be added.

[strvalue3]     The sub-directory that [strvalue2] will be placed either
        before or after.

[addopt]        Specify where [strvalue2] is to be placed: either BEFORE
        or AFTER [strvalue3].


Description - Adds a sub-directory to a path environment variable.

Tips:

1) If [strvalue3] is a null string, ADDPATH will place [strvalue2] in the
position of the path statement indicated by [addopt] (i.e., the new path
will be placed at the beginning or end of the path statement).

2) If the key specified in [strvalue1] is not found, then a new one is
added, with a "SET" prepended.  This allows for adding path like environment
variables such as "SET TEMP=", and so on.

3) This function can also be used to edit other lines such as a TEMP
environment variable, or any other line that does something like
"SET envvar=d:\path."

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example -  Add the sub-directory WINDOWS to the path and place it before
the DOS variable in the AUTOEXEC.BAT file:

    SETSYSFILE "C:\" "AUTOEXEC.BAT"
    ADDPATH "PATH" "C:\WINDOWS" "C:\DOS" BEFORE



CFGGETVALUE [strvalue] [intvar]

Parameter       Description and Notes
[strvalue]      The variable to be retrieved.

[intvar]        An integer variable to hold the retrieved value.
        (Before being used as a parameter, this variable must
        be defined using the DEFINE function.)


Description - Gets a numeric variable from a system file (e.g., FILES,
BUFFERS, etc.).

Tip - If the value of the key specified is non-numeric (e.g., the DOS=HIGH),
CFGGETVALUE sets parameter 2 to 0, but does not return an error code.
Use CFGGETSTRING to get a string value.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = -2 if the key value could not be found
[RETVAL] = DOS error code in all other cases

Example - Place the value of the FILES= statement in the CONFIG.SYS file
into a user defined variable called nRESULT (which must first be defined!):

    DEFINE "nRESULT" STRING
    SETSYSFILE "C:\" "CONFIG.SYS"
    CFGGETVALUE "FILES" nRESULT



CFGSETVALUE [strvalue] [intvalue]

Parameter       Description and Notes
[strvalue]      The variable to be set.

[intvalue]      The integer value.


Description - Sets a numeric variable in a system file (e.g., FILES,
BUFFERS, etc.).

Tip: Use ADDLINE to add a new statement if one does not exist.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = -2 if the key value could not be found
[RETVAL] = DOS error code in all other cases

Example - Set the value of the FILES= statement in the CONFIG.SYS file to 50,
provided a FILES= statement already exists in the file:

    SETSYSFILE "C:\" "CONFIG.SYS"
    CFGSETVALUE "FILES" 50
    CFGGETSTRING [strvalue] [strvar]
    CFGSETSTRING [strvalue1] [strvalue2]

These two functions act exactly the same as CFG???VALUE, except they deal
with string values rather than integer values.  An administrator might use
this to check non-numeric variables (e.g., STACKS=9,256 is a non numeric
value).

Note that before using the [strvar] variable as a parameter, the variable
must be defined using the DEFINE function.



REPLACEKEY [strvalue1] [strvalue2] [strvalue3]

Parameter       Description and Notes
[strvalue1]     The line in the system file which contains the key value
        to be replaced.

[strvalue2]     The key value to be replaced.

[strvalue3]     The new value.


Description - Similar to REPLACELINE; however, it replaces a key value
rather than the entire line.

Tip - If [strvalue3] is a null string, [strvalue2] will be removed.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example -  Change the "40" to a "50" in the FILES= line in the CONFIG.SYS
file:

    SETSYSFILE "C:\" "CONFIG.SYS"
    REPLACEKEY "FILES=40" "40" "50"



REPLACELINE [strvalue1] [strvalue2]

Parameter       Description and Notes
[strvalue1]     The key value of the line you wish to replace, such as PATH,
        COMSPEC or DEVICE.

[strvalue2]     The new value of the entire line.


Description - Replaces an existing line in a system file with a new line.

Tips:

1) If [strvalue2] is a null string, then the line will be deleted.

2) If the key value exists more than one time in the file, only the first
instance is modified.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example - Replace the existing COMSPEC line in the CONFIG.SYS file with a
new line:

    SETSYSFILE "C:\" "CONFIG.SYS"
    REPLACELINE "COMSPEC" "SET COMSPEC=C:\DRDOS\COMMAND.COM"


REPLACELINEADD [strvalue1] [strvalue2] [addopt]

Parameter       Description and Notes
[strvalue1]     The key value of the line you wish to replace, such as PATH,
        COMSPEC or DEVICE.

[strvalue2]     The new value of the entire line.

[addopt]        Where [strvalue1] is to be placed: either BEFORE or AFTER
        [strvalue2].


Description - Similar to REPLACELINE, this function replaces an existing
line in a system file with a new line.  However, if the key specified in
[strvalue1] is not found, then the line specified in [strvalue2] is added
to the file, at the beginning or end of the file depending on the position
defined by [addopt].

Tip: If [strvalue1] is not found, then the line specified as [strvalue2]
will be added to the file in the position defined by [addopt].

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example - Replace the existing NETX line with the new line C:\NET\VLM.
If NETX is not found, then the line will be appended to the end of the file:

    SETSYSFILE "C:\" "NET.BAT"
    REPLACELINEADD "NETX" "C:\NET\VLM" AFTER



SETSYSFILE [path] [filename]

Parameter       Description and Notes
[path]          The path to the file to be modified.

[filename]      The name of the file to be modified.


Description - Sets a system file to be manipulated.

Tips:

1) This function must be called prior to calling any of the functions in
the Easy System File function category.  It needs to be called only once,
unless you change the file you are working on in the script.

2) Using [BOOT_ROOT] as the [path] parameter will always modify the file on
the boot disk, regardless of whether or not the user is given the option to
override the installation path (in the package definition).  Use [TARGET]
as the [path] parameter if the user is given the option to override the
installation path.

Return Values:

[RETVAL] = 0 if file is found
[RETVAL] = 2 if file is not found

Example -  Designate a user's CONFIG.SYS file as the file to be edited.
Two examples of this are:

    SETSYSFILE "C:\" "CONFIG.SYS"
    or
    SETSYSFILE [BOOT_ROOT] "CONFIG.SYS"


7.6 Windows System File Functions

The Windows System File functions provide the ability to edit INI files
and create and manipulate Program Manager groups.

NOTES:  a - In the following function specifications, parameters in
quotes represent literal parameters; all other parameters represent rules.
The rules are listed in section 7.8 entitled "DOS Error Codes."
b - Many of the Windows System File functions have a [pathfile] parameter
which specifies the path name and file name to an INI file.  If you do
not specify a full path to the Windows directory, then the actions
performed by these functions occur on the first instance of Windows found,
as determined by the path statement of the receiving machine.  If Windows
is not found in the path, then the distribution update program will search
for the INI file in [BOOT_ROOT]\WINDOWS.  If Windows is still not found,
the update program will then try [BOOT_ROOT]\WIN31.
c - The functions ADDGROUP, ADDITEM, and SCHEDULEWIN use the WSDUPD.EXE
update program which is copied into the local Windows directory each
time these functions are used.  The next time the user runs Windows,
WSDUPD.EXE runs and executes the appropriate function(s).  It then deletes
WSDUPD.EXE and WSDUPD.INI.  If a user has SHARE.EXE loaded, a
"sharing violation" message will display when trying to delete WSDUPD.EXE.
This message can be ignored.


ADDGROUP [strvalue]

Parameter       Description and Notes
[strvalue]      The string which specifies the name of the Program Manager
        group to be added.


Description - Creates a new Program Manager group.

Tip: When the ADDGROUP script function is executed, the BrightWorks
software distribution update program WSDUPD.EXE is automatically copied
into the workstation's Windows directory.  The WSDUPD.EXE command is also
added to the "Load=" line in the WIN.INI file.  The next time Windows is
run at the workstation, the function is executed and WSDUPD.EXE is removed
from the WIN.INI "Load=" line.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code if unsuccessful.  The function might fail if
WSDUPD.EXE could not be copied into the Windows directory or if the
WSDUPD.EXE control file (WSDUPD.INI) could not be created.

Example -  Create a Program Manager group named COMPANY:

    ADDGROUP "COMPANY"

NOTE:  This function can be used with any third party shell program which
emulates the Program Manager DDE interface.



ADDITEM [strvalue1] [strvalue2] [pathfile]

Parameter       Description and Notes
[strvalue1]     The group to which the item will be added.

[strvalue2]     The name of the new item.

[pathfile]      The .EXE file to be associated with the new item.


Description - Adds a new item to a Program Manager group.

Tip: When the ADDITEM script function is executed, the BrightWorks
software distribution update program WSDUPD.EXE is automatically copied
into the workstation's Windows directory.  The WSDUPD.EXE command is
also added to the "Load=" line in the WIN.INI file.  The next time
Windows is run at the workstation, the function is executed and WSDUPD.EXE
is removed from the WIN.INI "Load=" line.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code if unsuccessful.  The function might fail if
WSDUPD.EXE could not be copied into the Windows directory or if the
WSDUPD.EXE control file (WSDUPD.INI) could not be created.

Example -  Create a Program Manager group named APPS, and then create a
program icon within the new APPS group named EXCEL:

    ADDGROUP "APPS"
    ADDITEM "APPS" "EXCEL" "U:\MS\EXCEL\EXCEL.EXE"

NOTE:  This function can be used with any third party shell program which
emulates the Program Manager DDE interface.
Also note that the path specified will appear in the command line as well as
the working directory. The above EXCEL example demonstrates this.



GETINIINT [pathfile] [strvalue1] [strvalue2] [intvar]

This function works in exactly the same way as GETINISTR (below) except
it is used to retrieve integer values from INI files.



GETINISTR [pathfile] [strvalue1] [strvalue2] [strvar]

Parameter       Description and Notes
[pathfile]      The path and file name of the INI file.

[strvalue1]     The section of the INI file in which the entry is located
        (e.g., [386Enh]).

[strvalue2]     The entry whose associated string is to be retrieved
        (e.g., keyboard.drv=, however, do not include the = sign!).

[strvar]        Variable in which to place the found string.  (Before being
        used as a parameter, this variable must be defined using
        the DEFINE function.)


Description - Gets a key value (string) from an INI file, and places the
result in a variable.

Tip - If [strvalue2] is a null string or the key is not found, ADDDEVICE
will add [strvalue1] in the position of the file indicated by [addopt].

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = -1 if the [strvalue2]  section name does not exist
[RETVAL] = -2 if the [strvalue3]  key does not exist
[RETVAL] = DOS error code in all other cases

Example -  Determine whether Windows version 3.1 is installed at a
workstation by looking at the CONTROL.INI file:

    DEFINE "VER" STRING
    GETINISTR "C:\WIN\CONTROL.INI" "[INSTALLED]" "3.1" VER



SCHEDULEWIN [path] [filename] [text]

Parameter       Description and Notes
[path]          The path to the file to be run.

[filename]      The file name to be run upon Windows execution.

[text]          Optional command line arguments for the file.


Description - Schedules a file to be run the next time the user runs Windows.

Tip - This function could be used to automate the installation of a
Windows program if a macro playback utility is used.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code if unsuccessful.  The function might fail if
WSDUPD.EXE could not be copied into the Windows directory or if the
WSDUPD.EXE control file (WSDUPD.INI) could not be created.

Example -  Schedule the Notepad program to run the next time Windows is run,
and also open the README.TXT notepad file:

    SCHEDULEWIN "C:\WINDOWS" "NOTEPAD.EXE" "README.TXT"


WRITEINIINT [pathfile] [strvalue1] [strvalue2] [intvalue]

This function works exactly like WRITEINISTR (below), except that it is
used to write an integer value to an INI file.


WRITEINISTR [pathfile] [strvalue1] [strvalue2] [strvalue3]

Parameter       Description and Notes
[pathfile]      The path and file name of the INI file.

[strvalue1]     The section in which [strvalue2] is located (e.g., [386Enh]).

[strvalue2]     The entry whose associated string is to be modified
        (e.g., keyboard.drv=, however, don't include the = sign!).

[strvalue3]     The string to be written to the INI file.


Description - Gets a key value (string) from an INI file, and writes the
result to the INI file.

Tips:

1) If the section name specified in [strvalue1] is not found, then it will
be added to the end of the INI file, with a new key=value added in that
section.

2) If the [strvalue1] section is found but the key value specified in
[strvalue2] is not found, the new key value is added directly after the
section name [strvalue1].

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = DOS error code in all other cases

Example -  Define a "medium priority" in the [SPOOLER] section of the
WIN.INI file:

    WRITEINISTR "C:\WIN\WIN.INI" "[SPOOLER]" "PRIORITY" "MEDIUM"



7.7 Miscellaneous Functions

The Miscellaneous Functions include basic functions for defining, assigning,
copying, comparing and concatenating variables.

NOTE:  In the following function specifications, parameters in quotes
represent literal parameters; all other parameters represent rules.
The rules are listed in section 7.8 entitled "DOS Error Codes."


APPENDPATH [strvar] [strvalue]

Parameter       Description and Notes
[strvar]        The variable to contain the appended string
        (i.e., destination).  (Before being used as a parameter,
        this variable must be defined using the DEFINE function.)

[strvalue]      The string value to be appended (i.e., source).


Description - Adds a file name to a path or builds a path.  This function
acts the same way as STRCAT, except that it will check if the last
character of [strvar] is a "\".  If it is not, APPENDPATH will append
a "\" to [strvar], and then [strvalue] will be appended.  This is very
useful (and necessary!) in building paths.

Return Value:

[RETVAL] = 0 always

Example - Define the variable named PATH to be a string-type.  Copy the
location of the network configuration files into the PATH variable and
then append it to the C:\DRIVERS directory.

    DEFINE "PATH" STRING
    STRCOPY PATH [NETCFG]
    APPENDPATH "C:\DRIVERS" PATH



ASSIGN [intvar] [intvalue]

Parameter       Description and Notes
[intvar]        The integer type variable name which will be assigned a
        value.  (Before being used as a parameter, this variable
        must be defined using the DEFINE function.)

[intvalue]      The numeric value to be assigned to the integer type variable.


Description - Performs a basic integer assignment operation (e.g., a = b).

Return Value:

[RETVAL] = 0 always

Example -  Define the variable "NUM" as an integer type, and later assign
33 to the variable NUM:

    DEFINE "NUM" INTEGER
    ASSIGN NUM 33



DEFINE [text] [defineopt]

Parameter       Description and Notes
[text]          The variable being defined.

[defineopt]     The type of variable being defined (e.g., STRING or INTEGER).


Description - Used to create user defined variables of a string or integer
type.  This variable can then be used later in the script.

Tips:
1) All DEFINE statements must be declared before any script command
is executed.

2)  If a STRING type variable is declared, the login module will allocate
255 bytes (= 255 characters) of memory for the string.  If an INTEGER
type variable is declared, the login module will allocate 4 bytes (C type
long which equals to an approximately -2 billion to +2 billion size integer).

Return Value:

[RETVAL] = 0 always

Example -  Define the variable "ANSWER" as a string type.

    DEFINE "ANSWER" STRING



EXIT [intvalue]

Parameter       Description and Notes
[intvalue]      An integer type variable.


Description - Ends the script.

Tips:

1) If [intvalue] is set to a non-zero value, then the login module will
increment the error count by one for the upgrade package and note the log
with the error number returned.

2) If the package has been defined to execute the script before decompressing
the fileset, then the EXIT command will prevent the decompression of the
fileset.  (For more information on defining "Advanced Package Options,"
refer to the section later in this chapter.)

Return Value: none

Example -  End the script if an obtained value is greater than 50:

    IF RESULT <= 50
        CFGSETVALUE "FILES" 55
    ELSE
        EXIT 1
    ENDIF


IF [intvalue1] [condoper] [intvalue2] ... {ELSE...} ENDIF

Parameter       Description and Notes
[intvalue1]     An integer type variable to be evaluated against [intvalue2].

[condoper]      Valid conditional operators are: =, !=, <, >, <=, >=

[intvalue2]     An integer type variable to evaluate [intvalue1] against.

Description - Allows conditional processing of functions.  IF..THEN
evaluates the conditional expression defined by [intvalue1] [condoper]
[intvalue2].  If the condition evaluates to be TRUE, then all functions
following THEN are executed until an ELSE or ENDIF is reached.  If the
condition evaluates to FALSE and ELSE is defined, then all functions
following the ELSE are executed until an ENDIF is reached.

Tip - IFs can be nested up to 50 levels deep.

Return Value: none

Example -  Obtain the FILES= value from the CONFIG.SYS file.  If the value
is less than or equal to 50, then change the value to 55; otherwise, exit
the script:

    DEFINE "RESULT" INTEGER
    SETSYSFILE "C:\" "CONFIG.SYS"
    CFGGETVALUE "FILES" RESULT
    IF RESULT <= 50
        CFGSETVALUE "FILES" 55
    ELSE
        EXIT 1
    ENDIF


NUMTOSTR [strvar] [intvalue]

Parameter       Description and Notes
[strvar]        The variable to contain the converted value.  (Before being
        used as a parameter, this variable must be defined using
        the DEFINE function.)

[intvalue]      The numeric value to be converted.


Description - Converts a numeric value to a string variable.

Return Value:

[RETVAL] = 0 always

Example -  Convert the number 100 to a string and store the value in the
defined variable named ONEHUNDRED:

    DEFINE "ONEHUNDRED" STRING
    NUMTOSTR ONEHUNDRED 100


PAUSE [text]

Parameter       Description and Notes
[text]          The text to be displayed on the user's screen during the
        pause. (This can be NULL)


Description - Pauses execution of the script until the user presses a key.

Tip - If [text]1 is NULL, then the default message "Strike any key to
continue" is displayed on the screen.

Return Value = 0 always

Example -  Display the message "Pausing... press any key to continue"
during script execution.

    PAUSE "PAUSING ... PRESS ANY KEY TO CONTINUE."



REBOOT

This function immediately reboots the user's PC.  It does not accept any
parameters and does not return any values.  Before the reboot, the script
file is closed, the log database is closed, and any necessary cleanup is
performed.

NOTES: a - The PC will not reboot if a fileset is to be executed after the
script.
b -  The REBOOT function might not work if the workstation is not 100% PC
compatible.


SHELL [pathfile] {text} {shellopt}

Parameter       Description and Notes
[pathfile]      The path and file name to execute.
{text}          The file's optional command line arguments.  (This can be
        NULL.)

{shellopt}      Optional argument which can only be either [KEEPPATH] or NULL.


Description - Allows a user to execute an external DOS batch file,
executable program, or DOS command.

Tip - To execute the program or batch file in [pathfile] and change to the
specified path, use the KEEPPATH option as the {shellopt} parameter.  If
you don't specify the KEEPPATH option, SHELL will try to use the path from
which the SDUPDATE program was run.  KEEPPATH allows you to temporarily
switch to the path from where you want to run the program.

Return Values:

[RETVAL] = 0 if successful
[RETVAL] = -1 if failed

Example -  Execute LIST.COM and load the contents of the README.TXT file.
Temporarily make the current directory C:\PUB\LIST.COM.

    SHELL "C:\PUB\LIST.COM" "README.TXT" "" KEEPPATH


STRCAT [strvar] [strvalue]

Parameter       Description and Notes
[strvar]        The variable to contain the concatenated string
        (i.e., destination).  (Before being used as a parameter,
        this variable must be defined using the DEFINE function.)

[strvalue]      The string value to be appended (i.e., source).


Description - Appends the contents of [strvalue] to the end of the string
[strvar].

Tip - If the resulting text in [strvar] is longer than the space allowed
(255 bytes), then it will be truncated and properly null terminated.

Return Value:

[RETVAL] = 0 always

Example -  Add the string "ADDTHIS" to a string variable named STRINGS1&2:

    DEFINE "STRINGS1&2" STRING
    STRCAT STRINGS1&2 "ADDTHIS"


STRCOMPARE [strvar] [strvalue]

Parameter       Description and Notes
[strvar]        The variable to be compared.  (Before being used as a
        parameter, this variable must be defined using the
        DEFINE function.)

[strvalue]      The value to compare the variable against.


Description - Does a byte for byte comparison of two strings.

Return Values:

[RETVAL] = 0 if the strings are identical
[RETVAL] = < 0 if [strvar] is less than [strvalue]
[RETVAL] =  > 0 if [strvar] is greater than [strvalue]

Example -  Check the current NetWare login name against a specified login
name ("Supervisor").

    DEFINE "NAME" STRING
    STRCOPY NAME [LOGINNAME]
    STRCOMPARE NAME "SUPERVISOR"


STRCOPY [strvar] [strvalue]

Parameter       Description and Notes
[strvar]        The variable to receive the copied string value
        (i.e., destination).  (Before being used as a parameter,
        this variable must be defined using the DEFINE function.)

[strvalue]      The string value to be copied (i.e., source).


Description - Copies a value into a string, overwriting the previous
contents of the string.

Return Value:

[RETVAL] = 0 always

Example -  Copy the string "ABC" into the string variable named "HOLDABC":

    DEFINE "HOLDABC" STRING
    STRCOPY HOLDABC "ABC"


WRITELN [strvalue]

Parameter       Description and Notes
[strvalue]      The string to display on screen.


Description - Writes the [strvalue] line to stdout (e.g., the screen).
This might be useful for displaying error messages, etc.

Return Value:

[RETVAL] = 0 always

Example -  Define the variable named RESULT.  Place the value of the
FILES= statement in the CONFIG.SYS file into RESULT, and then write the
value of RESULT.

    DEFINE "VALUE" STRING
    DEFINE "RESULT" INTEGER
    SETSYSFILE "C:\" "CONFIG.SYS"
    CFGGETVALUE "FILES" RESULT
    NUMTOSTR VALUE RESULT
    WRITELN VALUE



7.8 Rules and System Variables

Most of the functions in the BrightWorks script language have parameters
that are specified or passed to them.  The valid entries for each parameter
type are called rules.  For example, the UPGRADEOS function has one
parameter named [upgopt].  As indicated in the table below, the value of
the [upgopt] parameter can be either 5.00 or 6.00.  Therefore, the
allowable values for the [upgopt] parameter are 5.00 and 6.00.

NOTE:  When a user defined variable of string type is expected, [STRVAR] is
the rule.  When a user defined variable of integer type is expected,
[INTVAR] is the rule.

The table below lists the rules (allowable values) for each parameter.

Rule Name       Allowed Values
ADDOPT          BEFORE AFTER
ATTRIBUTE       RO  RW  A  SY  H  SH -A -SY -H -SH
CONDOPER        <  >  =  !=  >=  <=
DEFINEOPT       STRING  INTEGER
DELETEOPT       ALL
FILENAME        [STRVAR] "filename.ext" (wild cards not allowed for file name)
FILEWILD        [STRVAR] "filename.ext" "*.*" (wild cards are allowed but
        not required for a file name)
INTVALUE        [INTVAR] [RETVAL]  # (where # is a valid integer)
INTVAR          [INTVAR]
PATH            [STRVAR] "path" [TARGET] [BOOT_ROOT] [WINDIR] [WINSYSDIR]
        [NETCFG] [HDRIVE] [NDRIVE] [SERVERNAME] [LOGINNAME]
        [FUSIONNAME] [LOGSCRNAME]
PATHFILE        [STRVAR] "{path\}filename.ext"
SHELLOPT        KEEPPATH
STRVAR          [STRVAR]
STRVALUE        [STRVAR] "text" [TARGET] [BOOT_ROOT] [WINDIR] [WINSYSDIR]
        [NETCFG] [HDRIVE] [NDRIVE] [SERVERNAME] [LOGINNAME]
        [FUSIONNAME] [LOGSCRNAME]
TEXT            "text"
UPGOPT          5.00 6.00


7.8.1 System Variables

The rules listed in the above table are defined as follows:

7.8.2 String Type Rules:

[BOOT_ROOT] - the root of the boot drive of the workstation on which the
script is executed

[HDRIVE] - drive letter of the first available hard drive  (may be boot or
network drive)

[FUSIONNAME] - primary user name from BrightWorks databases (generally same
as LOGINNAME)

[LOCATION] - location field from BrightWorks inventory databases

[LOGINNAME] - login name of user

[LOGSCRNAME] - full path and file name of login script for user running
update.

[NDRIVE] - drive letter of the first available network drive

[NETCFG] - path to NET.CFG used at NetWare shell load (must be in path)

[SERVERNAME] - name of server on which the update program is running

[TARGET] - installation path as defined by the administrator (or changed
by user, if able to)

[WINDIR] - the user's Windows directory (directory in which the login
module finds WIN.INI - this directory must be in the path)

[WINSYSDIR] - the user's Windows\System directory (directory in which the
login module finds USER.EXE - this directory may be in the SYSTEM
directory below WINDIR, or in the path)

7.8.3 Integer Type Rules:

[DISKSPACE] - available disk space in drive specified in [TARGETDIR].
The number is in bytes.

[RETVAL] - return code of last command completed


7.9 DOS Error Codes

The following lists the DOS error codes that may be returned from the
script functions.  For each error, the number, message, reason, action,
and functions that return the error are described.

o Message # 2 - "File not found." Reason: file specified in the script
does not exist. Check the filename and path. Functions returning error:
GETINISTR() - The file from which you requested a string does not exist.
GETINIINT() - The file from which you requested an integer does not exist.

o  Message # 3 -  "Path not found." Reason: a directory path specified
in the script does not exist.  Check the path and directory name.  Functions
returning error: DELETEDIR() - The directory that you requested to delete
does not exist, or it does not exist in the location you specified.

o  Message # 4 - "Too many open files (no handles left)." Reason:
insufficient file handles are specified in CONFIG.SYS.  Increase the
number of file handles in CONFIG.SYS.  Functions returning error: COPY()
All Easy System File and Windows System File functions.

o  Message # 5 - "Access denied." Reasons: specified drive or file cannot
be accessed. Insufficient user rights, read only files, disk full. Verify
the user rights, file attributes and available disk space. Functions
returning error: DELETEFILE(), ADDPATH(), ADDLINE(), REPLACELINE(),
REPLACEKEY(), ADDDEVICE(), CFGSETVALUE(), CFGSETSTRING(), REPLACELINEADD(),
WRITEINISTR(), WRITEINIINT() - Is the file flagged read only?  Is the
disk full?  Does the end user have insufficient rights in the specified
directory?  DELETEDIR() - Subdirectories and/or files exist, and the
"ALL" option was not used in the script.  ADDGROUP(), ADDITEM(),
SCHEDULEWIN() - Is WIN.INI flagged read only?

o  Message # 8 - "Insufficient memory" Reason: Not enough memory to
complete the specified action. Unload unnecessary TSRs, check workstation
memory management.  Functions returning this error: All DOS, Easy System
File and Windows System File functions.

o  Message # 15 - "Invalid drive" Reason: The drive specified does not
exist. Check the drives specified in the script. Functions returning this
error: All DOS, Easy System File and Windows System File functions.

o  Message # 16 - "Attempt to remove current directory" Reason: The
directory you attempted to delete is active on a drive.  Functions returning
this error: DELETEDIR() - Is the directory specified active on the drive?
If it is a network drive, are other users active on the drive?

o  Message # 17 - "Not same device" Reason: An action was specified on
two separate drives.  Ensure that you are not attempting to "cross drives"
on an action that does not permit this (e.g., RENAME)  Functions returning
this error: RENAME() - Are the source and target locations different?

o  Message # 18 - "No more files"  Reason: The specified file could not be
found.  Check the path and filename. Check end user rights in the directory
specified.  Functions returning this error: DELFILE(), ATTRIB(), RENAME(),
SETSYSFILE(),  COPY() - Does the specified file exist in the location
specified?  Does the end user have sufficient rights to see the file?

o  Message # 19 - "Disk is write protected"  Reason:  The write protect
tab is enabled on the disk specified in the operation.  Remove the write
protect tab.  Functions returning this error:  All DOS, Easy System File
and Windows System File functions.

o  Message # 21 - "Drive not ready"  Reason: There is no disk in the drive
specified in the operation. Insert the diskette.  Functions returning this
error: All DOS, Easy System File and Windows System File functions.

o  Message # 22 - "Invalid disk command"  Reason: Media access error.
Check the diskette or drive. Functions returning this error: Bad or
damaged diskette.

o  Message # 23  - "CRC error"  Reason: Media access error.  Check the
diskette or drive.  Functions returning this error: Bad or damaged diskette.

o  Message # 24 - "Invalid length"  Reason: Media access error.  Check the
diskette or drive. Functions returning this error: Bad or damaged diskette.

o  Message # 25 - "Seek error"  Reason: Media access error.  Check the
diskette or drive.  Functions returning this error: Bad or damaged diskette.

o  Message # 27 - "Sector not found"  Reason: Media access error.  Check
the diskette or drive.  Functions returning this error: Bad or damaged
diskette.

o  Message # 29 - "Write fault"  Reason: Media access error.  Check the
diskette or drive.  Functions returning this error: Bad or damaged diskette.

o  Message # 30 - "Read fault"  Reason: Media access error. Check the
diskette or drive.  Functions returning this error: Bad or damaged diskette.

o  Message # 31 - "General failure"  Reason:  Media access error.  Check
the diskette or drive.  Functions returning this error:  Diskette may
not be formatted.



8.0 Scopes

Chapter 7 discussed the software distribution script language  This
chapter discusses the creation and management of scopes--the group of
workstations defined to receive a distributed package.



8.1 Introduction

A scope is a group of workstations defined to receive a distributed
package.  Defining a scope is as easy as assigning a name to the new
scope.  After the scope is created, any number of workstations can be
included in the scope definition.

8.1.1 Scope Features

By taking advantage of the database of inventory information maintained
by BrightWorks, users can create scopes by selecting from nodes that match
specific filtering criteria.

The filtering criteria is saved as a "query" and then applied against the
database to narrow down the list of applicable workstations.  Scope
membership is subsequently assigned using the list of nodes that match the
user-specified filtering criteria.  Items such as CPU speed, workstation
memory and installed software can be used to accommodate a scope's intent.
For example, a scope named CPU386 might consist of the network's 386
workstations; a scope named 386>16MHz might consist of the network's 386
workstations that also have a CPU clock frequency greater than 16 MHz.

Scopes and queries can be stored, used and reused as resources within
BrightWorks.  A user can create a new scope, as well as edit, copy,
rename and delete a scope.  The steps for managing both scopes and queries
are provided in this chapter.

8.1.2 Access to Scope Functions

Scope functions are accessed by choosing the Scopes command from the
Tools menu.  The Scopes dialog box displays listing all available scopes.

8.1.3 What's in this Chapter

The following chart describes the sections in this chapter:

SECTION                 DESCRIPTION
Creating Scopes         Describes procedures for defining new scopes.

Scope Queries           Describes procedures for applying queries to
            scopes, removing queries from scopes, creating
            new queries, editing queries and deleting queries.

Managing Scopes         Describes procedures for editing, renaming,
            copying and deleting scopes.


8.2 Creating Scopes

Use the following procedure to create a new scope.

NOTE:  At least one audit must have been run in order to create a scope.

1.  Choose the Scopes command from the Tools menu.

    The Scopes dialog box displays listing the names of all defined scopes.

2.  Choose the New button.

    The New Scope dialog box displays prompting you to enter a name for
    the new scope.

3.  Enter the new scope name, and choose the OK button.

    A scope name can be up to 80 characters, and all typed characters are
    valid.  For example, enter the new scope name "386/16MHZ" which will
    include the network's 386/16MHz nodes.

    Upon choosing the OK button, the Edit Scope dialog box displays
    prompting you to define the new scope.

    The Edit Scope dialog box consists of two lists:

    o  Nodes in SITE - the list on the left side of the dialog box
    consists of all node names that apply to the local site.  The
    site name is indicated by the SITE text in the list title. The
    nodes in this list are not included in the selected scope
    (i.e., the list to the right).

    o  Nodes included in Scope - the list on the right side of the
    dialog box consists of the nodes that are in the selected scope.

NOTE:  The Query Options section of the Edit Scope dialog box is used to
perform a query to filter the node names in the Nodes in SITE list.
For detailed instructions on performing queries, refer to the next
section of this chapter entitled "Scope Queries."

4.  Define the nodes to be included in the scope.

    Use the push buttons in the center of the Edit Scope dialog box to
    define the scope members.  To define scope membership, select a node
    name from either list and choose the appropriate button:

    o  Include >> - choose this button to include the selected node
    in the scope.  The node name moves from the left list to the right
    list.

    o  Include All - choose this button to include all listed nodes in
    the scope.  All node names move from the left list to the right list.

    o  << Remove - choose this button to remove the selected node from
    the scope.  The node name moves from the right list to the left list.

    o  Remove All - choose this button to remove all nodes from the
    scope.  All node names move from the right list to the left list.

NOTE:  Because user names can be edited via the View Inventory Details
dialog box, the node names in the Nodes in SITE list do not necessarily
correspond to NetWare user names.  As a result, there may be duplicate
names in this list.  Viewing the inventory details of nodes with the same
name enables you to differentiate between the nodes.  Choose the View
button or double click on a name in either list to invoke the View
Inventory Details dialog box for the selected node.

5.  When the scope members are defined, choose the Save button.


8.3 Scope Queries

When no filtering criteria is applied to a scope, all nodes in the
local BrightWorks site are listed in the Nodes in SITE list of the Edit
Scope dialog box.  This condition is indicated by the <None> entry in
the Last Query field.

Searching through a large list of nodes might make the process of
defining scope membership cumbersome.  Applying a query to a scope refines
the number of nodes in the Nodes in SITE list so that scope membership
can be made from a "qualified" list of nodes.

NOTE:  Only one query can be applied to a scope at any time.  Each query
can consist of more than one filtering criteria.  An applied query
always filters from the entire list of nodes in the local BrightWorks site.

Queries can be saved and applied to any number of scopes.  The same queries
can be applied to BrightWorks inventory and distribution reports, as is
discussed in Chapter 9 of the LAN Inventory manual.

This section lists the procedures for:
o  Creating a new query
o  Editing a query
o  Deleting a query
o  Applying a query to the scope
o  Removing a query from the scope

8.3.1 Creating a New Query

Use the following procedure to create a new query.  The procedure assumes
that you have already chosen the Select button in the Edit Scope dialog
box to display the Select Query dialog box.

NOTE:  All queries are also available when generating BrightWorks
inventory and distribution reports, as discussed in Part Three,
Chapter 9 of the LAN Inventory manual.

1.  Choose the Add button in the Select Query dialog box.

    The Add Query dialog box displays.  Press the <TAB> key to move
    from field to field within this dialog box.

2.  Enter a Query Name and define a filter entry.

    The purpose of each filter entry is to narrow down the list of nodes
    that apply to the specified criteria.  If more than one filter entry
    is defined, the entries are "linked" using either the AND or OR
    relationship.

    For example, assume the following two filter entries:

    Central Processing Unit = Intel_80386
    CPU Clock Frequency > 66.00 Mhz

    If the entries are linked with the OR relationship, only the nodes
    that satisfy either criteria (i.e., all Intel 80386 machines and
    all machines that have a clock speed greater than 66 Mhz) are
    included in the database sort.

    If the entries are linked with the OR relationship, the nodes that
    satisfy either criteria (i.e., all 286 machines and all machines
    that have a 720k floppy drive) are included in the database sort.

    For each filter entry, specify the following:

    o  Query Name - Enter a query name up to 80 characters in length.

    o  Component - Choose a component from the BrightWorks inventory
    database to use as the filter basis.  Select a component from the
    drop-down list associated with this field (e.g., Brand, Computer
    Model, CPU Clock Frequency).

    o  Condition - Choose a conditional operator from the drop-down
    list associated with this field (e.g., equal to, less than,
    greater than, not equal to).  'Equal to' is the default condition.

    o  Description - If desired, choose a description of the component.
    The items which automatically display in this list depend on the
    selected component.  For example, "Intel_80386" might display if
    Central Processing Unit is entered in the Component field;
    "16.00 Mhz" might display if CPU Clock Frequency is entered in the
    Component field.  See Note (a) below.

    o  Query Link - Specify the relationship between the filter
    entries (e.g., Central Processing Unit = 80386 OR Central
    Processing Unit = 80486).  The link options are AND and OR.
    See Note (b) below.

NOTES:  a - To create a query which tests for the presence of a
component, leave the Description field blank.  For example, to include
all nodes with a hard disk, construct a query with the following entries:

    Component =
    Hard Disk #1 < >

In this case, the Component description is left blank, and the query
results in including all nodes which have a hard disk (i.e., Hard Disk
#1 does not equal blank).
b - All filter entries in a query must have the same Query Link type
(e.g., all entries will be linked by AND or all entries will be linked by OR).

3.  Choose the Insert button to accept the filter entry definition.

    The entry is added to the Current Query List in the Edit Query dialog box.

4.  If required, insert additional filter entries.

    Repeat steps #2 and #3 above.

NOTE:  To add a filter entry between existing entries, first highlight
the filter entry line in the Current Query list where you want the new
entry to be placed.  The new defined entry is placed in the highlighted
position.

5.  When all filter entries are defined, choose the Save button.

    The query is saved and added to the Available Queries list in the
    Select Query dialog box.  The new query can now be applied to a scope.

8.3.2 Editing a Query

Use the following procedure to edit the definition of an existing query.
The procedure assumes that you have already chosen the Select button in the
Edit Scope dialog box to display the Select Query dialog box.

1.  Select a query from the Select Query dialog box, and choose the Edit
    button.

    The Edit Query dialog box displays showing the defined filter entries
    for the query.

2.  Modify the filter information, and choose the Save button.

    To delete a filter entry, highlight the entry in the Current Query
    List and choose the Delete button.

    To add a filter entry, specify the Component, Condition and Description,
    and choose the Insert button.  (For detailed instructions on adding
    filter entries, refer to the procedure above entitled "Creating a
    New Query.")

NOTE:  New filter entries are appended to the end of the Current Query
List unless a filter entry is selected.  If an existing filter entry is
selected, then the new filter entry gets inserted above it when you
choose the Insert button.

8.3.3 Deleting a Query

Use the following procedure to delete an existing query.  The procedure
assumes that you have already chosen the Select button in the Edit Scope
dialog box to display the Select Query dialog box.

1.  Select the query to be deleted from the Select Query dialog box, and
    choose the Delete button.

    A prompt displays asking you to confirm the deletion.

2.  Choose the Yes button to delete the query.

    If deleted, the query name is removed from the Available Queries list.

NOTE:  Queries that are currently applied to a scope and/or BrightWorks
inventory and distribution report can be deleted.

8.3.4 Applying a Query to the Scope

Use the following procedure to apply an existing query to a scope.  The
procedure assumes that you have already chosen the Edit button in the
Scopes dialog box to display the Edit Scope dialog box.

1.  Choose the Select button in the Query Options section of the Edit
    Scope dialog box.

    The Select Query dialog box displays listing all defined queries.

2.  Select the query name from the Available Queries list, and choose the
    Apply button.

    To select a query name, point to the query and click the left mouse
    button.

NOTE:  Applying a query to a scope causes a Printing Status dialog box to
display while the database records are being sorted.  When this occurs,
nodes are being selected (i.e., the information is not being sent to the
printer).

    The Select Query dialog box closes, and the selected query name is
    placed into the Last Query field of the Edit Scope dialog box.  The
    BrightWorks database records are sorted, and only the records that
    match the query's specified filter criteria will display in the Nodes
    in SITE list.  Now you can assign scope members using a "qualified"
    list of nodes.

NOTE:  If you already selected nodes to be included in the scope
(i.e., the nodes listed in the Nodes Included in Scope list), the nodes
continue to be "included" even if they do not match the filter criteria.

8.3.5 Removing a Query from the Scope

Use the following procedure to remove a scope query.

1.  Choose the Select button in the Query Options section of the Edit
    Scope dialog box.

    The Select Query dialog box displays.

2.  Select the <None> query name, and choose the Apply button.

    The Select Query dialog box closes.  All nodes in the local BrightWorks
    site are listed in the Nodes in SITE list of the Edit Scope dialog box.

8.3.6 Creating a Complex Query

A query can consist of any number of filter entries that are defined to
produce a desired result.  The relationship between the filter entries is
referred to as the "link."

Assume that you are responsible for upgrading the workstations of all
network users in the Sales Department who are currently using Intel 286
machines with a CPU speed less than 16 MHz and which have a 1.44 megabyte
floppy disk designated as drive A:.

Use the following procedure to create a query that defines the scope of
users in the above example.

1.  In the Add Query dialog box, enter a Query Name.

    Enter a name that uniquely identifies this query
    (e.g., "Sales 286/16Mhz").

2.  Define the first filter entry, and choose the Insert button.

    Enter the following for each field:

    Component: Department
    Condition: =
    Description: Sales
    Query Link: AND

3.  Define the second filter entry, and choose the Insert button.

    Enter the following for each field:

    Component: Central Processing Unit
    Condition: =
    Description: Intel_80286
    Query Link: AND

4.  Define the third filter entry, and choose the Insert button.

    Enter the following for each field:

    Component: CPU Clock Frequency
    Condition: <
    Description: 16MHz
    Query Link: AND

5.  Define the fourth filter entry, and choose the Insert button.

    Enter the following for each field:

    Component: Floppy Disk #1
    Condition: =
    Description: A: 1.44 M
    Query Link: AND

6.  Choose the Save button to save the query.

    The filter entries in the Current Query list in the Edit Query
    dialog box should be identical to the following:

    Department = Sales
    Central Processing Unit = Intel_80286    AND
    CPU Clock Frequency < 16MHz      AND
    Floppy Disk #1 = A: 1.44 M       AND



8.4 Managing Scopes

8.4.1 Editing Scopes

Editing a scope may become necessary under two circumstances:

o  Existing scopes might need to be edited in order to add or delete
members according to a change in a scope's intent.

o  Scopes that are attached to packages might need to be edited when
re-sending packages.

Scope members are the nodes that are defined as a group to receive a
distributed package.

NOTE:  An existing scope can be edited even if the scope is part of a
scheduled package.  This is useful if you need to re-send a package to
a node(s).  If new nodes are added to a scope that is included in an
active package, then the package will automatically get distributed to
the new nodes.

Use the following procedure to edit a scope.  The procedure assumes that
you have already chosen the Scopes command from the Tools menu to
display the Scopes dialog box.

1.  Select the scope from the list of Scopes, and choose the Edit button.

    A scope can also be selected for editing by double clicking on the
    scope name in the Scopes dialog box.  The Edit Scope dialog box displays.

    The Edit Scope dialog box consists of two lists:

    o  Nodes in SITE - the list on the left side of the dialog box
    consists of all node names that apply to the local site.  The
    site name is indicated by the SITE text in the list title.  The
    nodes in this list are not included in the selected scope
    (i.e., the list to the right).

    o  Nodes included in Scope - the list on the right side of the
    dialog box consists of the nodes that are in the selected scope.

NOTE:  The Query Options section of the Edit Scope dialog box is used
to perform a query to filter the node names in the Nodes in SITE list.
for detailed instructions on performing queries, refer to section 8.3
entitled "Scope Queries."

2.  Define the nodes to be included in the scope.

    Use the push buttons in the center of the Edit Scope dialog box to
    define the scope members.  To define scope membership, select a node
    name from either list and choose the appropriate button:

    o  Include >> - choose this button to include the selected node
    in the scope.  The node name moves from the left list to the right
    list.

    o  Include All - choose this button to include all listed nodes
    in the scope.  All node names move from the left list to the right
    list.

    o  << Remove - choose this button to remove the selected node
    from the scope.  The node name moves from the right list to the
    left list.

    o  Remove All - choose this button to remove all nodes from the
    scope.  All node names move from the right list to the left list.

NOTE:  Because user names can be edited via the View Inventory Details
dialog box, the node names in the Nodes in SITE list do not necessarily
correspond to NetWare user names.  As a result, there may be duplicate
names in this list.  Viewing the inventory details of nodes with the same
name enables you to differentiate between the nodes.  Choose the View
button or double click on a name in either list to invoke the View Inventory
Details dialog box for the selected node.

3.  When the scope members are defined, choose the Save button.

8.4.1 Renaming Scopes

Use the following procedure to rename a scope.  The procedure assumes
that you have already chosen the Scopes command from the Tools menu to
display the Scopes dialog box.

NOTE:  A scope can be renamed even if it is part of an actively scheduled
package.

1.  To rename a scope, select the scope from the list of Scopes, and
    choose the Rename button.

    The Rename Scope dialog box displays prompting you to enter a new
    scope name.

2.  Enter the new scope name, and choose the OK button.

    The new scope name displays in the Scopes dialog box, and the old
    name is removed.  All attributes of the old scope are preserved in the
    renamed scope (i.e., the scope members do not change).

8.4.2 Copying Scopes

Use the following procedure to copy a scope.  The procedure assumes
that you have already chosen the Scopes command from the Tools menu to
display the Scopes dialog box.

NOTE:  A scope can be copied even if the original scope is part of an
actively scheduled package.

1.  To copy a scope, select the scope from the list of Scopes, and
    choose the Copy button.

    The Copy Scope dialog box displays prompting you to enter a name for
    the new scope.

2.  Enter the new scope name, and choose the OK button.

    The new scope name is added to the Scopes dialog box.  The new scope
    members are identical to the original scope members.


8.4.3 Deleting Scopes

Use the following procedure to delete a scope.  The procedure assumes
that you have already chosen the Scopes command from the Tools menu to
display the Scopes dialog box.

NOTE:  A scope that is part of a scheduled package cannot be deleted.

1.  To delete a scope, select the scope from the list of Scopes, and
    choose the Delete button.

    A prompt displays asking you to confirm the deletion.

2.  Choose the Yes button to delete the scope.

    If deleted, the scope name is removed from the Scopes dialog box.



9.0 Packages

Chapter 8 discussed the creation and management of scopes.  This chapter
discusses the creation and management of packages--the method by which
software is distributed across your network.



9.1 Introduction

Creating and activating a package is the method by which software is
distributed across your local area network.  When a package is created,
it is assigned a scope and a "Start Date."  Upon reaching the start date
and running the SDUPDATE.EXE program at a workstation in the scope, an
active package automatically gets sent to the workstation.

A package also consists of a fileset and/or a script to be distributed to
the group of remote workstations.  For example, a package named
UPGRADE_DOS might include a scope of users running DOS 3.3.  The package
might also include a script which installs a fileset consisting of the
DOS 6.0 files.

The software distribution update program (SDUPDATE.EXE) is integrated
with the packaging functionality.  The update program is responsible for
determining the conditions for accepting or rejecting a package.  The
program is also responsible for reporting on package status as input to the
Packages window and the Software Distribution Log.

9.1.1 Package Features

In addition to the contents and scope, every package is assigned a schedule
and a method for delivery.  A package's schedule is the date on which the
package is to be distributed.  The method of delivery specifies instructions
for the receiving workstation.  There are several options available to
the workstation user when a package is received.  For example, package
ABC might be configured to prompt the user five times to accept the
package before proceeding with the installation of its fileset.

A user can create a new package, as well as edit, rename and delete a
package.  The steps for each procedure are discussed in this chapter.

9.1.2 Access to Package Functions

Most package functions are accessed by either:

o  choosing the Packages command from the Tools menu, or
o  choosing the Distribute tool bar button

Both of the above actions cause the Packages window to display.

Package management is performed by either choosing the buttons in the
Packages window or by choosing the corresponding commands from the File
menu.  For example, when the Packages window is active, a new package
can be created either by choosing the New button in the Packages window
or by choosing the New Package command from the File menu.

The information in the Packages window is updated according to an
interval called the "package timer."  Package timer functions are accessed
by choosing the Distribution command from the Administration menu.

9.1.3 What's in this Chapter

The following chart describes the sections in this chapter:

SECTION                         DESCRIPTION
Creating and Editing Packages   Describes procedures for defining new
                packages and for editing existing packages.

Managing Packages               Describes procedures for renaming,
                activating/deactivating, and deleting
                packages.

The Package Timer               Describes procedures for setting the
                package timer interval.



9.2 Creating and Editing Packages

Use the following procedure to create a new package.

1.  Choose the Packages command from the Tools menu, or choose the
    Distribute tool bar button.

    The Packages window displays.  This window lists the names of all
    defined packages.  For each package, the following is indicated:

    o  Start Date - the date the package will be distributed
    o  Status - the package's status (Active or Inactive)
    o  Total - the total number of workstation in the package's scope
    o  Done - the number of successful updates so far
    o  Errors - the total number of failed attempts at performing
    an update

NOTE:  Packages that have the same Start Date are distributed in the
order in which they appear in the Packages window.  To change a
package's priority, refer to section 9.3.1 entitled "Prioritizing
Packages."

2.  Choose the New button in the Packages window.

    The New Package dialog box displays prompting you to enter a name
    for the new package.

3.  Enter the new package name, and choose the OK button.

    The package name can be up to 80 characters, and all typed characters
    are valid.

    Upon choosing OK, a New Package dialog box displays.  The name of the
    new package is indicated in the title bar of the dialog box.

4.  Select a fileset and/or a script to be included in the package.

    Choose the down arrow button to the right of the Update Fileset
    and/or Update Script fields to display the list of existing filesets
    and scripts.  Select the desired items from the drop-down lists.

NOTE:  A package must include either one fileset or one script, or both.

5.  Select the scope to receive the package.

    Choose the down arrow button to the right of the Update Scope field
    to display the list of existing scopes.  Select a scope from the
    drop-down list.

NOTE:  A scope must be assigned to the package.

6.  Assign the package's Start Date.

    Enter the date on which the package is to be distributed.  The current
    date appears as a default in this field.  Use the up/down arrow buttons
    to the right of the Start Date field to scroll to the desired date,
    or press the <F4> key to display a calendar from which a date can be
    selected.

7.  Assign the Active or Inactive status to the package.

    Check the "Update active when saved" option to automatically place
    the package in an active state upon saving the package.  (An active
    package will get distributed automatically on its assigned start date.)

    If this field is not checked, an Inactive status will be assigned to
    the package.  An inactive package will not get distributed
    automatically on its assigned start date.

8.  Specify the package's update option.

    The selected Update Option instructs the software distribution update
    program how it should interact with the receiving workstation user at
    login time.

    The four Update Options are:

    o  Force upgrade at next login - This option forces the package's
    receipt on the user at the next login.  If an error occurs, the
    distribution is halted so the administrator can address the
    problem and reschedule the package.

    o  User optional until [DATE] and then [ABANDON, FORCE] update -
    This option allows the user to refuse the package until the
    indicated DATE.  After the DATE, the package is either abandoned
    or forced to be received by the user.

    o  User optional, prompt user [# TIMES] and then [ABANDON, FORCE]
    update - This option allows the user to refuse the package a
    certain number of times (# TIMES).  After the threshold is reached,
    the package is either abandoned or forced to be received by the user.

    o  Run this package always - This option forces the package's
    receipt on the user at each and every login.  This update option
    is most useful in situations where system variables are being
    modified directly by users.

9.  Specify the target path in which the fileset should be decompressed.

    A default path must be assigned to the package.  The default path is
    the target path in which the distributed software (i.e., fileset) is
    to be installed or copied.

    The default path can be:

    o  entered as a hard-coded drive mapping and directory
    combination (e.g., C:\BIN\DRIVERS).

    o  entered as a hard-coded server, volume and directory
    combination (e.g., SERVER/VOLUME:\DIR or VOLUME:\DIR).  If a
    server is specified, then the user receiving the package must be
    attached to the server.

    o  reliant upon a system configuration found at the receiving
    workstation.  Reliance is implemented by using one of the following
    target default path options available from the drop down list
    associated with this field:

        - [BOOT_ROOT] - the root of the receiving machine's boot
        disk
        - [HDRIVE] - the receiving machine's first hard drive
        - [NDRIVE] - the receiving machine's first network drive
        - [NETCFG] - path to the receiving machine's network
        configuration (which must be in the path)
        - [WINDIR] - the receiving machine's Windows directory
        (the directory in which the login module finds WIN.INI -
        this directory must be in the path)
        - [WINSYSDIR] - the receiving machine's Windows\System
        directory (directory in which the login module finds
        USER.EXE - this directory may be in the SYSTEM directory
        below WINDIR, or in the path)

    These variables can be used in combination with a hard-coded value
    (e.g., [WINSYSDIR]\TEMP).  In this case, the backslash character (\)
    is required and the variable name must be first.  If a specified
    directory does not exist, it will be created.

    If desired, check the "Allow user to override installation path" option
    to allow the user at the receiving workstation to override the selected
    path.

10. To define advanced package options, choose the Advanced button.

    The Advanced Options dialog box displays.  The advanced package
    options consist of the following categories:

    o  Windows Error Options - options associated with how the software
    distribution update program should react in the event that the Windows
    directory is not discovered at a receiving workstation.

    o  Fileset and Script Options - options which define the execution
    precedence for the package's fileset and script  (e.g., which one
    the software distribution update program should run first at the
    receiving workstation).

    o  Script Error Options - options associated with how the software
    distribution update program should react in the event of script errors.
    (The script function error codes are detailed in Chapter 7 of this
    manual, "Software Distribution Script Language.")

NOTE:  Several script functions may return a non-zero value that is not
considered to be an error.  For example, the FINDFILE function returns
a -1 if the file is not found; the STRCOMPARE function returns non-zero
value if the two strings are not equal.  You might want to disable the
Script Error Options when using functions that return non-zero values even
when successful.

11. When all package attributes are defined, choose the Save button.

9.2.1 Editing Packages

Editing a package may be necessary in order to modify package attributes.

Use the following procedure to edit the attributes of a package.  The
procedure assumes that you have already chosen the Packages command from
the Tools menu to display the Packages window.

1.  To edit package attributes, select the package from the Packages
    window, and choose the Edit button.

    A package can also be selected for edit by double clicking on the
    package name in the Packages window.  The Edit Package dialog box
    displays showing the configuration of the selected package.  The
    fields and options in this dialog box are identical to the New Package
    dialog box.

    The name of the package being edited displays in the title bar of
    the Edit Package dialog box.

2.  Modify the package attributes.

    Changes can be made to any field except the Update Scope, Update
    Fileset and Update Script fields.

NOTES: a - Although the package's scope, fileset and script cannot be
changed, their definition can be changed.  For example, if Scope ABC
is assigned to the package, you cannot assign Scope XYZ to the package
but you can edit the members of scope ABC.
b - If a package fails, it can be re-distributed to a user by first
removing the user from the scope and saving the edited scope, and then
adding the user back into the scope and again saving the edited scope.
Be careful when doing this because editing a scope changes all instances
of the scope (i.e., even those included in packages).

    If the distribution of a package has already begun, the changes made
    to the package take effect on the next node in the scope to receive
    the package.

3.  Choose the Save button.

    The Packages window re-displays.

NOTE:  To display the Software Distribution Log History details
associated with a package, highlight the package in the Packages window
and choose the Details button.  The Log Details dialog box displays
showing the details for the selected package.  This dialog box is discussed
in Chapter 10.


9.3 Managing Packages

9.3.1 Prioritizing Packages

The priority with which each package is run is determined by its position
in the Packages window.  Packages that have the same Start Date are
distributed in the order in which they are listed.

To modify a package's run time, highlight the package in the Packages
window, and choose either the Up or Down buttons.  The highlighted package
will be moved in the selected direction.

For example there are two packages scheduled to be distributed on
1/12/1994.  Because of their position in the list of packages, WIN_INI
will be distributed before UPDATED SYSTEM FILES.  To change their
distribution order, highlight the UPDATED SYSTEM FILES fileset and
choose the up arrow button.

Also note that the status of the TUTORIAL package is "Complete (A)."
The (A) indicates that although the package has been distributed to all
workstations in the scope, the package is still active.  Therefore, if
the package's scope is edited to include additional nodes, the package will
automatically get distributed to those new nodes.

9.3.2 Renaming Packages

Changing the name of an existing package renames the package in the
Packages window.

Use the following procedure to rename a package.  The procedure assumes
that you have already chosen the Packages command from the Tools menu
to display the Packages window.

NOTE:  Actively scheduled packages can be renamed.

1.  To rename a package, select the package from the Packages list, and
    choose the Rename button.

    The Rename Package dialog box displays prompting you to enter a new
    package name.

2.  Enter the new package name, and choose the OK button.

    The new package name displays in the Packages window, and the old
    name is removed.  All attributes of the old package are preserved in
    the renamed package (i.e., the package's scope, script and/or fileset
    definitions do not change).

9.3.3 Activating/Deactivating Packages

New packages are assigned the Active status if the Update Active when
Saved option is selected.  An active package automatically gets distributed
upon reaching its assigned Start Date.  An inactive package will not get
distributed until it is re-activated.

The status indication of a selected package in the Packages window
toggles between Active/Inactive by choosing the Activate/Deactivate
toggle button in the Packages window.

The status of a completed package (i.e., a package that has been sent to
all nodes in its scope) remains active.  Its status is indicated by
"Complete (A)."  By highlighting the completed package and choosing the
Deactivate toggle button, the status changes to "Complete (I)" which
indicates an inactive status.

9.3.4 Deleting Packages

Use the following procedure to delete a package.  The procedure assumes
that you have already chosen the Packages command from the Tools menu to
display the Packages window.

NOTE:  Actively scheduled packages cannot be deleted.  To delete a package
with an Active status, first make the package status Inactive by
highlighting the package and choosing the Deactivate button.  Then
perform the Delete action.

1.  To delete a package, select the package from the Packages window,
    and choose the Delete button.

    A prompt displays asking you to confirm the deletion.

2.  Choose the Yes button to delete the package.

    If deleted, the package name is removed from the Packages window.

NOTE:  Deleting a package does not delete the associated log entry in
the Software Distribution Log History dialog box.


9.4 The Package Timer

The Packages window displays the status of each scheduled package.
Status information includes the number of workstations in the package's
scope (Total), the current number of successful updates (Done) and the
total number of failed attempts at performing an update (Errors).  The
window contents are updated according to a defined package timer interval.

Use the following procedure to set the package timer and define the
interval at which the Packages window data is updated.

1.  Choose the Distribution command from the Administration menu.  From
    the sub-menu that displays, choose the Set Package Timer command.

    The Set Package Timer dialog box displays.

2.  Enter the time interval at which the Packages window should be
    updated, and choose the OK button.

    Enter the time in seconds.  (The default is 30 seconds.)  The
    information in the Packages window will be updated at the defined
    interval.

NOTE:  The status of the Packages window can also be updated on demand
by choosing the Distribution command from the Administration menu.
From the sub-menu that displays, choose the Query Now command.



10.0 Monitoring Software Distribution

Chapter 9 discussed the creation and management of packages.  This
chapter discusses the procedures for using the Software Distribution Log
History dialog box to monitor the success of distributed packages.



10.1 Introduction

The chronological events associated with scheduled packages can be
viewed from the Software Distribution Log History dialog box.  The log
history provides the information necessary for monitoring the success or
failure of a distributed package.  For example, if package WINUPDATE is
distributed to a scope having three members, the installation of the
software and update details for all three receiving workstations can be
verified via the log history details.

10.1.1 Access to the Software Distribution Log

The Software Distribution Log History dialog box is displayed by choosing
the Distribution command from the Administration menu.  From the sub-menu
that displays, choose the View Distribution Log command.

The Software Distribution Log History dialog box is also displayed by
choosing the Details button in the Packages window.

10.1.2 What's in this Chapter

The following chart describes the sections in this chapter:

SECTION                         DESCRIPTION
The Software Distribution Log   Describes procedures for viewing and
                maintaining Log history details.


10.2 The Software Distribution Log

10.2.1 Viewing Log History Details

Use the following procedure to monitor and maintain the log history of
distributed packages.

1.  Choose the Distribution command from the Administration menu.  From
    the sub-menu that displays, choose the View Distribution Log command.

    The Software Distribution Log History dialog box displays.  The history
    log provides a summary of all scheduled packages.  The following
    information is provided for each package:

    o  Start Date - the date the package will be distributed
    o  Total - the total number of workstation in the package's scope
    o  Done - the number of successful updates so far
    o  Errors - the total number of failed attempts at performing an
    update

NOTE:  The completed updates (Done column) may be greater than the number
of users scheduled to receive a package (Total column).  This can occur as
a result of rescheduling packages or when using the "Run this package always"
update option during package scheduling.

2.  To view the individual events of a package, select the package from
    the Software Distribution Log History dialog box, and choose the
    Details button.

    A package can also be selected by double clicking on the package name
    in the Software Distribution Log History dialog box.  The Log Details
    dialog box for the selected package displays.

    In addition to the distribution Date/Time and target Site Name, the
    Details of the package's chronological events are shown in three lines:

    o  Identification of the target workstation - node address, user name
    o  Additional target workstation information - location, asset tag
    o  Results - some possible results are:
        - Package installed successfully.
        - Error [#]: Script "[Script name]" has not been
        completed successfully.

NOTE:  The error numbers related to unsuccessful script execution are
documented in Chapter 7 of this manual, "Software Distribution Script
Language."  Non zero error numbers only display if the corresponding
option was selected when the package was created.  For instructions on
defining "advanced package options," refer to the previous chapter.

3.  To delete a log entry, select the package from the Software
    Distribution Log History dialog box, and choose the Delete button.

    The package is removed from the list of scheduled packages.

NOTE:  A log entry cannot be deleted if its associated package still exists.

4.  Choose the OK button to close the Software Distribution Log History
    dialog box.